# saQut Compiler Toolbox — Yol Haritası ve Yapılacaklar

> **Felsefe**: saQut bir derleyici değil, bir **derleyici alet çantasıdır**.
> Amacı en hızlı kodu üretmek, en güvenli sandbox'u kurmak veya en optimize
> binary'yi çıkarmak değildir. Amacı, **derleyicinin kendisidir**.
>
> Her aşama (Lexer, Parser, Optimizer, Compiler) birbirinden bağımsız,
> kendi parametreleriyle yönlendirilebilen, gerektiğinde devre dışı
> bırakılabilen birer **araç kutusu modülü** olarak tasarlanır.
>
> Geliştirici, isterse sadece token listesini alır, isterse AST'yi JSON
> olarak çeker, isterse sembol tablosunu inceler, isterse kodu çalıştırır.
> Bu, ileride LSP sunucusu yazmayı, IDE eklentileri geliştirmeyi ve
> kod hiyerarşisi görselleştirmeyi mümkün kılar.

---

## Temel Prensipler

1. **Her aşama bağımsız**: Lexer → Tokenizer → Parser → Optimizer → IR → Backend.
   Her biri tek başına çalışabilir, kendi parametrelerini alır.

2. **Her şey metadata**: Her token ve AST düğümü; dosya adı, satır, sütun,
   karakter offset'i taşır. Debug ve hata mesajları bu veri üzerine kurulur.

3. **AST bellek canavarı**: Token'lar AST'de yaşar. Kaynak kodun neredeyse
   birebir izdüşümü AST üzerinde korunur. Hiçbir bilgi atılmaz.

4. **Sembol tablosu aynı felsefede**: Basit yapı, çok veri. Her sembolün
   tanımlandığı yer, tipi, kullanıldığı tüm noktalar, scope bilgisi.

5. **Feature toggle**: Her keyword, her operatör, her optimizasyon adımı
   açılıp kapatılabilir. `--disable-while`, `--skip-constant-folding`.

6. **Çoklu çıktı formatı**: Düz metin, JSON, (ileride) HTML/SVG. Tüm ara
   gösterimler dışa aktarılabilir.

7. **IR merkezli backend**: Tüm backend'ler (C transpile, QBE, LLVM, JIT)
   aynı IR'den beslenir. Yeni backend eklemek = yeni bir IR yürüteci yazmak.

---

## Aşama 0: Metadata ve Konum Takibi

> **Hedef**: Her token ve AST düğümü nereden geldiğini bilsin.

### 0.1 SourceFile Yöneticisi
- [ ] `SourceFile` sınıfı: dosya adı, tam metin, satır başı offset'leri
- [ ] `SourceLocation` yapısı: `{file, line, column, offset}`
- [ ] `offset → (line, column)` dönüşümü (binary search ile O(log n))
- [ ] Çoklu dosya desteği (import/include için temel)

### 0.2 Lexer'a Konum Ekleme
- [ ] Lexer her `nextChar()`'da satır/sütun takibi yapsın
- [ ] `getLocation()` → mevcut konumu `SourceLocation` olarak döndürsün
- [ ] `INumber` yapısına `SourceLocation startLoc, endLoc` eklensin

### 0.3 Token'lara Konum Ekleme
- [ ] `Token` temel sınıfına `SourceLocation loc` eklensin
- [ ] Her token oluşturulurken konumu kaydedilsin
- [ ] `start`/`end` offset'leri `SourceLocation` ile değiştirilsin

### 0.4 AST Düğümlerine Konum Ekleme
- [ ] `ASTNode` temel sınıfına `SourceLocation loc` eklensin
- [ ] Her düğüm oluşturulurken ilgili token'ın konumu kopyalansın

---

## Aşama 1: Interpreter (CLI + Dosya)

> **Hedef**: `saqut` komutu ile REPL veya dosya çalıştırma.

### 1.1 CLI Altyapısı
- [ ] `argc/argv` ile komut satırı argümanları
- [ ] `./saqut` → REPL modu (etkileşimli)
- [ ] `./saqut file.sqt` → dosyayı çalıştır
- [ ] `./saqut --mode=parse file.sqt` → sadece AST üret
- [ ] `./saqut --mode=tokens file.sqt` → sadece token listesi
- [ ] `./saqut --mode=ir file.sqt` → sadece IR
- [ ] `./saqut --mode=symbols file.sqt` → sembol tablosu
- [ ] `./saqut --format=json file.sqt` → JSON çıktı

### 1.2 REPL Modu
- [ ] `>` komut istemi
- [ ] Her satır ayrı ayrı parse edilir
- [ ] `.ast` komutu → son ifadenin AST'sini göster
- [ ] `.tokens` komutu → son ifadenin token'larını göster
- [ ] `.symbols` komutu → şu ana kadarki sembolleri göster
- [ ] `.exit` / `.quit` → çıkış
- [ ] Çok satırlı giriş (bloklar için)

### 1.3 Dosya Modu
- [ ] Kaynak dosyayı oku → pipeline'ı çalıştır
- [ ] Çıktıyı seçilen formatta bas
- [ ] `-o output.json` → dosyaya yaz

---

## Aşama 2: AST'yi Bellek Canavarı Yapma

> **Hedef**: AST, kaynak kodun tam bir izdüşümü olsun.
> Hiçbir bilgi kaybolmasın. Token'lar AST'de yaşasın.

### 2.1 Token Tutma
- [ ] AST düğümleri token'ları **sahiplensin** (unique_ptr veya shared_ptr)
- [ ] `LiteralNode`, `IdentifierNode` → ilgili token'ı doğrudan tutar
- [ ] `BinaryExpressionNode` → operatör token'ını tutar
- [ ] Her statement → ilgili keyword token'ını tutar (`if` token'ı, `for` token'ı)

### 2.2 Kaynak Kod Parçası Erişimi
- [ ] `ASTNode::getSourceText()` → bu düğümün kaynak koddaki ham metni
- [ ] `ASTNode::getSourceRange()` → başlangıç/bitiş SourceLocation
- [ ] Hata mesajlarında kaynak kod parçası gösterimi:
  ```
  Hata: test.sqt:5:10: 'x' değişkeni tanımlı değil
    4 | int main() {
    5 |     y = x + 1;
      |         ^
    6 | }
  ```

### 2.3 AST Görselleştirme
- [ ] `--format=json` → tam AST'yi JSON olarak dök
- [ ] `--format=dot` → Graphviz DOT formatı (görsel ağaç)
- [ ] `--format=html` → Etkileşimli HTML ağaç görünümü (ileride)
- [ ] JSON çıktısı her düğüm için:
  ```json
  {
    "kind": "BinaryExpression",
    "operator": "PLUS",
    "location": { "file": "test.sqt", "line": 5, "column": 9 },
    "sourceText": "x + 1",
    "left": { ... },
    "right": { ... }
  }
  ```

---

## Aşama 3: Sembol Tablosu

> **Hedef**: AST kadar zengin, basit yapılı bir sembol tablosu.
> Her sembolün tüm kullanım noktaları, tip bilgisi, scope'u kayıtlı.

### 3.1 Symbol Sınıfı
- [ ] `Symbol` yapısı:
  - `name`: sembol adı
  - `kind`: variable, function, parameter, type, ...
  - `type`: tip bilgisi (şimdilik string, ileride Type sistemi)
  - `definitionLoc`: tanımlandığı SourceLocation
  - `references`: kullanıldığı tüm SourceLocation'ların listesi
  - `scope`: ait olduğu scope (global, function, block)
  - `metadata`: opsiyonel anahtar-değer çiftleri

### 3.2 SymbolTable Sınıfı
- [ ] İç içe scope desteği (global → function → block)
- [ ] `enterScope()` / `exitScope()`
- [ ] `define(name, kind, type, location)` → yeni sembol ekle
- [ ] `resolve(name)` → en yakın scope'tan başlayarak ara
- [ ] `addReference(name, location)` → kullanım noktası ekle
- [ ] `getAllSymbols()` → tüm scope'lardaki tüm semboller (düz liste)
- [ ] JSON'a serialize edilebilme

### 3.3 Sembol Toplama (AST Walker)
- [ ] `SymbolCollector` sınıfı: AST'yi dolaşır, sembolleri toplar
- [ ] Değişken tanımlarını yakala → `define()`
- [ ] Değişken kullanımlarını yakala → `addReference()`
- [ ] Fonksiyon tanımlarını yakala
- [ ] Hata durumları: tanımsız değişken, çift tanım, tip uyuşmazlığı

---

## Aşama 4: Feature Toggle Sistemi

> **Hedef**: Derleyicinin her özelliği açılıp kapatılabilir olsun.

### 4.1 CompilerConfig Yapısı
- [ ] `CompilerConfig` struct'ı:
  ```cpp
  struct CompilerConfig {
      // Dil özellikleri
      bool enableWhile     = true;
      bool enableFor       = true;
      bool enableDoWhile   = true;
      bool enableSwitch    = true;
      bool enableClass     = false;  // henüz yok
      bool enableInterface = false;
      bool enableEnum      = false;
      
      // Operatörler
      bool enableTernary   = true;
      bool enablePostfix   = true;
      bool enableUnary     = true;
      
      // Optimizasyon adımları
      bool optConstantFolding   = false;
      bool optDeadCodeElim      = false;
      bool optUnusedVariable    = false;
      
      // Çıktı
      std::string outputFormat  = "text";  // text, json
      std::string mode          = "run";   // tokens, ast, ir, symbols, run
      std::string inputFile;
      std::string outputFile;
  };
  ```

### 4.2 Keyword Kontrolü
- [ ] Tokenizer, config'te kapalı keyword'leri identifier olarak tanısın
- [ ] Parser, kapalı keyword'ler için hata değil, görmezden gelsin
- [ ] `--disable-while` → `while` artık bir keyword değil

### 4.3 Optimizasyon Kontrolü
- [ ] Her optimizasyon adımı bir `OptimizationPass` soyut sınıfı
- [ ] `OptimizationManager`: config'e göre pas'ları çalıştırır
- [ ] `--skip-constant-folding` → o adım atlanır
- [ ] `--opt-all` → tüm optimizasyonlar aktif
- [ ] `--opt-none` → hiçbiri aktif değil

---

## Aşama 5: Çoklu Backend Altyapısı (IR Merkezli)

> **Hedef**: Tüm backend'ler aynı IR'den beslenir.
> Yeni backend eklemek = yeni bir `IRRunner` yazmak.

### 5.1 IR'yi Güçlendirme
- [ ] Kontrol akışı: `br`, `jmp`, `cmp`, `br_eq`, `br_lt`, `br_gt`
- [ ] Fonksiyon: `call`, `ret`, `param`
- [ ] Bellek: `load`, `store`, `alloca`
- [ ] Tip bilgisi: her IR komutu tipleri taşısın
- [ ] Debug bilgisi: kaynak satır eşlemesi
- [ ] `IRModule` sınıfı: fonksiyon listesi, global değişkenler, IR komutları

### 5.2 Backend Arayüzü
- [ ] `IBackend` soyut sınıfı:
  ```cpp
  class IBackend {
  public:
      virtual bool initialize(CompilerConfig& config) = 0;
      virtual bool compile(IRModule& ir) = 0;
      virtual bool run() = 0;
      virtual std::string getOutput() = 0;
      virtual ~IBackend() = default;
  };
  ```

### 5.3 C Transpile Backend (Aşama 1)
- [ ] IR → C kaynak kodu dönüşümü
- [ ] Değişken tanımları, if/for/while, fonksiyonlar
- [ ] GCC/Clang ile derleme ve çalıştırma
- [ ] Üretilen C kodu okunabilir ve debug edilebilir olmalı

### 5.4 Interpreter Backend (Aşama 1)
- [ ] IR'yi doğrudan yürüten sanal makine
- [ ] Stack tabanlı veya register tabanlı
- [ ] Adım adım çalıştırma (step) desteği
- [ ] Değişken değerlerini gösterme

### 5.5 QBE Backend (Aşama 2)
- [ ] QBE C API'si ile entegrasyon
- [ ] IR → QBE IR dönüşümü
- [ ] Native binary üretimi

### 5.6 LLVM Backend (Aşama 3, opsiyonel)
- [ ] LLVM C API ile entegrasyon
- [ ] IR → LLVM IR dönüşümü
- [ ] Agresif optimizasyonlar, çok platformlu kod üretimi

---

## Aşama 6: Hata Sistemi

> **Hedef**: Sadece hata mesajı değil, **açıklama**.
> Kullanıcıya neyi yanlış yaptığını ve nasıl düzelteceğini söyle.

### 6.1 Diagnostic Sistemi
- [ ] `Diagnostic` yapısı: `{level, location, message, hint, sourceLine}`
- [ ] Seviyeler: error, warning, note, hint
- [ ] Birden fazla diagnostic toplama (ilk hatada durma)
- [ ] `DiagnosticEngine`: diagnostic'leri toplar, formatlar, basar

### 6.2 Hata Mesajı Formatı
- [ ] Kaynak satır gösterimi (^^^^ işaretleme)
- [ ] Renkli çıktı (opsiyonel, `--color`)
- [ ] JSON formatında da alınabilir
- [ ] Hata kodları (örn: E0001, W0002)

### 6.3 Zengin Hata Açıklamaları
- [ ] Tanımsız değişken → "x tanımlı değil. Bunu mu demek istediniz: xy?"
- [ ] Tip uyuşmazlığı → "int bekleniyor ama float verilmiş. Cast ekleyin."
- [ ] Eksik noktalı virgül → "; eksik. Bu satırın sonuna ekleyin."
- [ ] Sembol tablosu kullanarak bağlamlı öneriler

---

## Aşama 7: LSP Sunucusu (Uzun Vade)

> **Hedef**: VS Code ve diğer IDE'ler için tam dil desteği.
> Tüm metadata ve çoklu çıktı formatları LSP'yi kolaylaştırır.

### 7.1 LSP Protokolü Temelleri
- [ ] `initialize`, `shutdown`, `exit`
- [ ] `textDocument/didOpen`, `didChange`, `didClose`
- [ ] JSON-RPC 2.0 üzerinden iletişim

### 7.2 Dil Özellikleri
- [ ] **Syntax highlighting**: Token listesini LSP'e bildir
- [ ] **Diagnostics**: Hata/uyarıları anlık bildir
- [ ] **Go to definition**: Sembol tablosundan tanım konumuna git
- [ ] **Find references**: Sembolün tüm kullanım noktalarını bul
- [ ] **Hover**: İmleç üstündeki sembol hakkında bilgi göster
- [ ] **Code completion**: Bağlama göre öneriler (sembol tablosundan)
- [ ] **Document symbols**: Dosyadaki tüm sembolleri listele (AST'den)
- [ ] **Code lens**: Fonksiyon başına reference sayısı

### 7.3 Kod Hiyerarşisi Görselleştirme
- [ ] `--format=html` ile etkileşimli AST ağacı
- [ ] AST'yi JSON olarak alıp web UI'da görselleştirme
- [ ] Sembol tablosunu grafik olarak gösterme
- [ ] Fonksiyon çağrı grafiği (call graph)

---

## Aşama 8: Test ve Kalite

### 8.1 Birim Testleri
- [ ] Lexer testleri: her sayı formatı, her operatör, string
- [ ] Tokenizer testleri: keyword'ler, delimiter'lar, yorumlar
- [ ] Parser testleri: her statement tipi, iç içe ifadeler, hata durumları
- [ ] IR testleri: her opcode, doğru register tahsisi
- [ ] Sembol tablosu testleri: tanımlama, çözümleme, scope

### 8.2 Anlık Görüntü (Snapshot) Testleri
- [ ] `source.sqt` → `output.json` karşılaştırması
- [ ] Her commit'te AST/IR/sembol çıktısı değişmemeli (regresyon)

### 8.3 Benchmark
- [ ] Büyük dosya parse süresi
- [ ] Tokenizer throughput (token/saniye)
- [ ] Bellek kullanımı

---

## Öncelik Sıralaması

```
Şu an (Aşama 0) ──▶ Metadata ve konum takibi
                    │
Haftaya (Aşama 1) ──▶ CLI + REPL + dosya modu
                    │
2 hafta (Aşama 2) ──▶ Bellek canavarı AST + JSON çıktı
                    │
3 hafta (Aşama 3) ──▶ Sembol tablosu
                    │
4 hafta (Aşama 4) ──▶ Feature toggle + CompilerConfig
                    │
5 hafta (Aşama 5) ──▶ IR güçlendirme + C transpile backend
                    │
6 hafta (Aşama 6) ──▶ Diagnostic + zengin hata mesajları
                    │
... (Aşama 7-8)  ──▶ LSP, testler, benchmark
```

---

## Anlık Görevler (Bu Hafta)

### Bugün / Yarın
- [ ] `SourceLocation` yapısını tanımla (`src/core/location.hpp`)
- [ ] `SourceFile` sınıfını yaz (offset → satır/sütun dönüşümü)
- [ ] Lexer'a satır/sütun takibi ekle
- [ ] `INumber` yerine `SourceLocation` kullanan yeni yapı

### Bu Hafta
- [ ] Token'lara `SourceLocation` ekle
- [ ] AST düğümlerine `SourceLocation` ekle
- [ ] Token'ları AST'nin sahiplenmesi (unique_ptr)
- [ ] CLI modülü: argc/argv, temel komutlar

---

## Mimari Notlar

### Neden Bellek Canavarı?
Çünkü amaç **bilgiyi korumak**. Derleyiciler genelde parse ettikten sonra
kaynak kod bilgisini atar. Biz atmayacağız. Bu sayede:
- Hata mesajlarında kaynak kodu gösterebiliriz
- IDE'de "go to definition" yapabiliriz
- Kodu yeniden oluşturabiliriz (pretty printer)
- Dönüşümleri (refactoring) güvenle yapabiliriz

### Neden Feature Toggle?
Çünkü bu bir **toolbox**. Kullanıcı dili özelleştirebilmeli:
- Eğitim amaçlı: önce sadece if/else, sonra while ekle
- Deney amaçlı: "while olmadan program yazabilir misin?"
- Güvenlik: belirli yapıları yasakla (eval, system call)
- DSL: kendi alt-dilini oluştur

### Neden IR Merkezli?
IR, tüm backend'lerin ortak dilidir. Yeni bir backend eklemek
istediğimizde parser'ı, lexer'ı, optimizer'ı değiştirmemize gerek kalmaz.
Sadece IR → Hedef dönüşümü yazarız. Bu, LLVM dışında QBE, Cranelift,
hatta kendi JIT'imizi eklemeyi mümkün kılar.