# 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.