161 lines
11 KiB
Markdown
161 lines
11 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, zorunlu class/main boilerplate
|
||
yok. **Semantik (ADR-020):** primitive (`int`/`float`/`bool`) = **değer**;
|
||
bileşik (`struct`/`array`/`string`) = **referans** (JS/Java/C# modeli). "Pointer
|
||
yok" = kullanıcıya `&`/`*` **sözdizimi** verilmez; derleyici/runtime içeride ve
|
||
çalışma zamanında referansı sonuna kadar kullanır. **Yok:** OOP, closure,
|
||
generic, auto/tip çıkarımı, gizli int↔float (tek istisna sabit folding). **Var:**
|
||
struct, tipli fonksiyonlar, array (`int[]`). `class`/`function` sözdizimsel
|
||
**rezerve** (semantik ileride). `interface` **ertelendi** (ADR-018).
|
||
⚠️ Referans semantiği döngüsel-referans **sızıntısını** açtı → GC/döngü
|
||
toplayıcı borcu (**#56**, `karar-gerekli`).
|
||
- **Null güvenliği (ADR-021, REVİZE):** varsayılan non-null; nullable açıkça `Type?`
|
||
(Kotlin/Swift). `null` yalnızca `T?`'ye atanır; `T?` üstünde doğrudan erişim derleme
|
||
hatası. **Atama kuralı `T <: T?`** (notnull→nullable serbest, nullable→notnull yasak).
|
||
**Katı operand kuralı:** non-null bağlamda her operand statik non-null olmalı
|
||
(`int a=b+c+d`, biri nullable → hata). Aklama **yalnızca görünür `if` narrowing**
|
||
(nested + sıralı guard + `&&`; alias takibi yok). ⚠️ **`a!`/`??`/`?.` YASAK** (gizli
|
||
runtime null-aklama yok). Runtime maliyeti **sıfır**; frontend kesin çözer (backend
|
||
yeniden analiz etmez) → runtime null-deref esasen FFI backstop'u. SSA gerekmez (#2).
|
||
- **Bellek/GC (ADR-022):** **basit, taşımasız, stop-the-world, deterministik
|
||
mark-sweep** (döngüleri toplar, "cage" korunur). **`shared_ptr`'ı kalıcı model
|
||
YAPMA** (refcount döngüde sızar = topuğa-sıkma). Kural: nesne modelini **baştan
|
||
GC-hazır** kur (header: tip+mark biti+liste; VM kök sayar; nesne çocuk
|
||
referansları sayar). v1: toplamasız (arena); v2: aynı model üstünde mark-sweep.
|
||
Asıl perf-katili GC kararı → basit tutarak de-risk edildi.
|
||
- **Eşitlik (ADR-023):** `==` primitive'de değer, referans (struct/array) **kimlik**
|
||
(aynı nesne). Derin/yapısal eşitlik **asla** `==`'e bağlanmaz → ayrı görünür
|
||
`deepEquals()` (PHP `==`/`===`/`clone` ailesi gibi). **String istisnası:** `==`
|
||
**içerik** olmalı (Java gotcha'sından kaçın) → string'i immutable değer-tipi
|
||
modelle (#40). `obj==obj`'i hata yapmak + kullanıcı-tanımlı eşitlik = uzak gelecek.
|
||
- **String (ADR-024):** **immutable değer-tipi, iç temsil UTF-8.** `s = s + "x"`
|
||
yeni string üretir; `==` içerik (ADR-023). Bayt/scalar/grapheme erişimi açıkça
|
||
ayrı (sahte O(1) karakter indeksi YOK). Verimli birleştirme için ileride builder.
|
||
Çözdüğü: #40 (yüzey), #9 (iç temsil). Mevcut `Value` string'i inline tutuyor —
|
||
immutable olduğu için bu yeterli; heap/object-model'e taşımak zorunlu değil.
|
||
- **Hata yönetimi (ADR-025, #57):** **Swift-tarzı** yakalanabilir, **struct-tabanlı**
|
||
hata — OOP/extend YOK. Standart `Error { line; char; message; trace; code }`
|
||
(message=W/E metni, code=W/E kodu). **Klasik `try{}catch{}` bloğu, UNCHECKED**
|
||
(Java/C#/JS usulü): fonksiyon işaretlenmez (`noexcept`/`constexpr` tarzı YOK),
|
||
çağrıda `try f()` yok — developer'a güven, alışkanlık bozulmaz. Runtime null-deref
|
||
(NPE analoğu), array OOB, /0, `a!` patlaması → yakalanabilir hata (ADR-021'in runtime
|
||
backstop'u). `throw` ile kullanıcı da kaldırır. Deterministik stacktrace (IR satır
|
||
tablosu önkoşul). **Tuple → ertelendi** (ADR-014'teki "yok" gevşedi). `finally` yerine
|
||
ileride `defer`.
|
||
- **Tip dönüşümü (ADR-026, #42):** açık **`as`** (infix, sola-bağlı): `x as int`.
|
||
Yalnızca **skaler + string** arası; **struct/array cast YOK** (elle yapıcı fonksiyon —
|
||
derleyiciyi sade tutar, sessiz alan kaybı önlenir). Başarısızlık **hedef tipin
|
||
nullable'lığıyla:** `as int` → `Error` fırlatır; `as int?` → `null`. Ayrı `as?` YOK.
|
||
`float→int` sıfıra kırpar (NaN/Inf/taşma fallible). `int(x)` fonksiyon-stili reddedildi.
|
||
- **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-020 ile revize: referansla tutulan struct alanı
|
||
artık döngü kurabilir, `Node next` meşru). (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)
|
||
- **✅ Birinci kilometre taşı AŞILDI:** `examples/fibonacci.sqt`
|
||
(recursive + iterative) `saqut run` ile çalışıyor → `55\n55`.
|
||
- **Çalışıyor (tam pipeline):**
|
||
- Lexer, tokenizer, Pratt parser, AST + JSON serileştirmesi
|
||
- Sembol tablosu (iki-geçişli toplayıcı, döngüsel struct tespiti)
|
||
- Tip sistemi (`src/core/type.hpp`) + diagnostic motoru (`src/diagnostic/`)
|
||
- Tip denetleyici + yapısal doğrulayıcı (`src/semantic/`)
|
||
- Optimizasyon: constant folding (int/bool/logical) + dead code elimination
|
||
- IR üreteci (3-adresli, slot tabanlı) + bytecode VM (yorumlayıcı döngü)
|
||
- CLI: `tokens` / `ast` / `symbols` / `check` / `ir` / `run` (6 komut)
|
||
- **Henüz YOK (bilinen eksikler):**
|
||
- float/double codegen (tip sistemi var, IR opcode'u yok)
|
||
- struct IR (parse/semantik var, codegen yok)
|
||
- array IR (parse/semantik var, codegen yok)
|
||
- `%=` operatörü IR'da eksik (#37)
|
||
- Global değişken IR üretimi sessizce atlıyor (#38)
|
||
- W003 ölü kod uyarısı üretilmiyor (#36)
|
||
- DCE silinen düğümleri `delete` etmiyor — bellek sızıntısı (#35)
|
||
- **İ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…026 (frontend, analiz/optimizasyon,
|
||
çalıştırma modeli, FFI, interface, bellek, **değer/referans semantiği, null
|
||
güvenliği, mark-sweep GC, eşitlik, string, hata yönetimi, tip dönüşümü**).
|
||
- `docs/sonnet-handoff.md` — **Sonnet için uygulama promptu** (ADR-020…024'ü koda
|
||
döken sıralı görev planı; ilk görev: GC-hazır nesne modeli + array runtime).
|
||
- `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 `0.1.0`; `master` branch yok. 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.
|