103 lines
6.5 KiB
Markdown
103 lines
6.5 KiB
Markdown
# CLAUDE.md — saQut Proje Bağlamı
|
||
|
||
> Bu dosya her oturumda yüklenir. Amaç: projenin kimliğini, kilitli kararları,
|
||
> mevcut durumu ve çalışma konvansiyonlarını hızlıca hatırlatmak.
|
||
|
||
## İletişim
|
||
- **Kullanıcıyla TÜM yazışmalar Türkçe.** (Sahibi: Abdussamed ULUTAŞ.)
|
||
|
||
## Proje nedir?
|
||
saQut, **programlanabilir ve incelenebilir bir derleyici** — bir "alet çantası"
|
||
(toolbox). Asıl varlık sebebi dilin kendisi değil, **derleme sürecinin her
|
||
aşamasının dışarıdan görülebilir/müdahale edilebilir olması**: token'lar, AST,
|
||
sembol tablosu, optimizasyon öncesi/sonrası ve IR ayrı ayrı incelenebilir.
|
||
Uygulama dili **C++** (header-only eğilimli, ADR-003). CMake + Ninja. `build/`
|
||
git'te izlenir.
|
||
|
||
## Kilitli kararlar (değiştirme — gerekçeler ADR'lerde)
|
||
- **Çalıştırma modeli: IR + bytecode VM (yorumlayıcı döngü).** Tree-walker DEĞİL,
|
||
gerçek makine-kodu JIT DEĞİL (kapsam dışı; öncelik determinizm + incelenebilirlik,
|
||
ham hız değil). C'ye transpile ileride geçerli 2. backend. İleride makine kodu
|
||
gerekirse libgccjit/LLVM'e bağlanılır (çok uzak). Bellek = host C++ heap; özel
|
||
allocator yok. (ADR-015)
|
||
- **Dil kimliği:** prosedürel, C-ailesi sözdizimi, value semantics, zorunlu
|
||
class/main boilerplate yok. **Yok:** class/OOP, closure, generic, kullanıcı
|
||
pointer'ı (`*`/`&`), auto/tip çıkarımı, gizli int↔float (tek istisna sabit
|
||
folding). **Var:** struct, tipli fonksiyonlar, array (`int[]`). `interface`
|
||
**ertelendi** (reddedilmedi, ADR-018).
|
||
- **Analiz vs Optimizasyon:** Analiz orijinal AST üstünde annotation; optimizasyon
|
||
**klon** üstünde dönüşüm. `ASTNode::clone()` yük taşıyan merkezi bileşen
|
||
(parent pointer'lar + sembol tablosu remap edilir, ADR-007). Fixpoint döngüsü +
|
||
iterasyon tavanı (`maxFixpointRounds`, ADR-009).
|
||
- **Literal/tip kuralı:** tamsayı literali bağlama-göre tiplenir (`float x = 1;`
|
||
geçerli; `int y = 1.5;`→E003; değişken→değişken gizli dönüşüm yok). Döngüsel
|
||
by-value struct → E010. (ADR-010/011)
|
||
- **FFI seam:** kasıtlı "host fonksiyonu çağır" mekanizması (`callhost`); `print`
|
||
ilk müşteri (ADR-016). Batteries = sınır/FFI problemi, "zlib'i yeniden yaz"
|
||
değil; kripto asla elle yazılmaz (ADR-017).
|
||
|
||
## Mevcut durum (yapılan vs planlanan)
|
||
- **Çalışıyor:** lexer, tokenizer, Pratt parser, AST, AST'nin JSON serileştirmesi,
|
||
CLI iskeleti (`tokens`/`ast`/`symbols`/`run`), konum takibi, basit aritmetiği
|
||
düşüren minimal IR deneyi.
|
||
- **Planlı (henüz YOK):** sembol tablosu, semantik analiz, tip sistemi, diagnostic
|
||
motoru, optimizasyon, IR+bytecode VM ile çalıştırma.
|
||
- **Birinci kilometre taşı ("bitti" tanımı):** `examples/fibonacci.sqt`
|
||
(recursive + iterative) derlenip çalıştırılabilmeli.
|
||
- **İlke:** Önce uçtan uca tek **dikey dilim**, sonra çerçeve. Erken soyutlamadan kaçın.
|
||
|
||
## Belge haritası
|
||
- `readme.md` — toolbox çerçevesi, built-vs-planned, dil kimliği, çalıştırma modeli.
|
||
- `docs/fikirler.md` — ADR-001…005 (backend stratejisi, parser, header-only, token, IR).
|
||
- `docs/adr-frontend-analiz.md` — ADR-006…019 (frontend, analiz/optimizasyon,
|
||
çalıştırma modeli, FFI, interface, bellek).
|
||
- `docs/roadmap-frontend.md` — faz-faz uygulama planı (Faz 0–4 → fibonacci).
|
||
- `docs/transkript-frontend-tasarim.md` — tasarım oturumu transkripti.
|
||
- `examples/fibonacci.sqt` — geçerli referans program.
|
||
- `examples/parser-stress/` — yalnızca parser'ı zorlayan, **geçerli olmayan** fixture'lar.
|
||
|
||
## Gitea issue yönetimi
|
||
- Repo: `git.saqut.com/saqut/saqut-compiler` (Gitea). Cloudflare, Python-urllib
|
||
User-Agent'ını banlıyor → tarayıcı User-Agent'ı şart.
|
||
- `scripts/gitea.py` — API istemcisi (`~/.git-credentials`'tan kimlik okur).
|
||
Komutlar: `list/get/create/edit/comment`. Toplu issue üretimi:
|
||
`scripts/create_issues.py`, `create_future_issues.py`, `create_syntax_test_issues.py`.
|
||
- **Issue yapısı (bu oturumda kuruldu):**
|
||
- **#69–73** `faz-plani` — Faz 0–4 (Tip+Diagnostic, AST refactor, Symbol Table,
|
||
Semantik Analiz, Optimizasyon). Format: Giriş/Gelişme/Sonuç-Başarı Kriterleri +
|
||
mühendis-olmayan analiz.
|
||
- **#74–98, #111** `fikir` — IR/VM tasarımı, modül/import, tip genişletmeleri
|
||
(decimal/date/enum/string), FFI/builtin/stdlib, tooling (LSP/highlight/fmt),
|
||
gelecek vizyonu (time-travel debug, WASM playground, test bloğu, paket yöneticisi).
|
||
Format: Giriş/Gelişme/**Açık Sorular** (başarı kriteri YOK).
|
||
- **#99–105** `test-senaryosu` — kaynak kod + beklenen çıktı içeren golden-test'ler.
|
||
- **#106–110** `cli-ux`/`kalite-mimari` — CLI fikirleri, C/Java/Go tarzı tavsiyeler.
|
||
- LSP (#91) ve CLI (#107) **Tier 0–4** katmanlı yetenek haritası olarak yazıldı;
|
||
#111 ekosistem bağımlılık sırası.
|
||
|
||
## Lisans (LICENSE.md — bu oturumda yeniden yazıldı)
|
||
- **Model:** "Kaynağı Açık — Ticari Kullanımı Kısıtlı" (açık kaynak ama **özgür
|
||
yazılım değil**). Önceki GPL-tarzı copyleft metin niyetle çelişiyordu, değiştirildi.
|
||
- **Çekirdek ilke:** Gelir saQut'un **ürettiği Çıktıdan** elde edilir, **saQut'un
|
||
kendisinden değil.**
|
||
- **Serbest (ticari dahil):** kod yazmak/derlemek, üretilen programları/exe/işlenmiş
|
||
veriyi satmak, derleyiciyi özel araç olarak iç kullanım.
|
||
- **İzin gerektirir (telif sahibinden):** derleyiciyi 3. tarafa kurup ücret almak,
|
||
Web-IDE/derleme servisi, canlı backend motoru, otomasyon/AI aracı, alt-bileşen
|
||
gömme, iç parçaları (AST/optimizatör) ticari yeniden kullanım. Runtime'a bağımlı
|
||
sürümlerde sunucu-tarafı ticari kullanım da bu kapsamda.
|
||
- **Maddeler:** §7 Katkı (PR herkese açık, **merge kararı yalnızca Abdussamed
|
||
ULUTAŞ**; katkı sahipleri ticari lisanslama dâhil hakları telif sahibine verir),
|
||
§8 Patent (lisans + dava açana otomatik fesih), §9 Marka ("saQut" adı korunur),
|
||
§11 Fesih (ihlalde otomatik + 30 gün düzeltme; edinilmiş Çıktı korunur).
|
||
- Üç dilde (TR/EN/DE), TR esas. Ticari lisans iletişimi: saqutsoftware+gitea@gmail.com
|
||
- **Not:** Bespoke lisans; ciddi ticari aşamada hukukçu gözden geçirmesi önerilir.
|
||
Telif yalnızca kodu/belgeyi korur, **fikri/tasarımı değil** (sıfırdan yeniden
|
||
yazım engellenemez); isim ise marka ile korunur.
|
||
|
||
## Çalışma konvansiyonları
|
||
- Commit mesajları sonunda: `Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>`.
|
||
- Ana dal `master`; commit/push kullanıcı isteyince yapılır.
|
||
- Wiki API'si Gitea'da REST üzerinden çalışmadı; wiki içeriği `wiki.md`'ye yazılıp
|
||
kullanıcı tarafından elle yapıştırılıyor.
|