saqut-compiler/CLAUDE.md

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.