@ -0,0 +1,452 @@
# saQut Derleyici ve Dil Ekosistemi — Aşamalı ı
> **Son güncelleme:** 2026-05-26
> **Amaç:** Bu belge, saQut derleyicisinin ve onu çevreleyen araç zincirinin aşamalı ı ı ı ı ı ı ı ı ı ı
---
## Vizyon (Kı ı
saQut bir derleyici değil, bir **derleyici alet çantası ı Amacı ı ı ı ı ı ı ı ı ı ı ı ı ı ı ı ı ı
---
## Genel Bağı ı ı ı
Aşağı ı ı ı
```
Lexer ─────────────────────────────────────────────────────────────────────┐
│ │
├── TextMate Syntax Highlighting (regex tabanlı ı
│ │
└── Tokenizer ──────────────────────────────────────────────────────┐ │
│ │ │
└── Parser ────────────────────────────────────────────────┐ │ │
│ │ │ │
├── AST ────────────────────────────────────────┐ │ │ │
│ │ │ │ │ │
│ ├── AST Analizi (node sayı ı
│ ├── Kod Biçimlendirici (pretty printer) │ │ │ │
│ └── Dokümantasyon Üretici (/// yorumlar) │ │ │ │
│ │ │ │ │
└── Sembol Tablosu ─────────────────────────┐ │ │ │ │
│ │ │ │ │ │
├── Tip Sistemi ──────────────┐ │ │ │ │ │
│ │ │ │ │ │ │ │
│ ├── LSP Diagnostics │ │ │ │ │ │
│ ├── LSP Hover (tip göster) │ │ │ │ │ │
│ ├── LSP Completion │ │ │ │ │ │
│ └── Linter / Statik Analiz │ │ │ │ │ │
│ │ │ │ │ │ │
├── LSP Go to Definition ──────┤ │ │ │ │ │
├── LSP Find References ───────┘ │ │ │ │ │
├── LSP Document Symbols │ │ │ │ │
├── LSP Semantic Tokens (renklendirme) │ │ │ │ │
└── Kod Haritası
│ │ │ │ │
┌───────────────────────────────────────┘ │ │ │ │
│ │ │ │ │
└── IR (Intermediate Representation) ───┐ │ │ │ │
│ │ │ │ │ │
├── C Transpile Backend │ │ │ │ │
├── Interpreter (Tree-walk / VM) │ │ │ │ │
├── QBE / Custom Backend │ │ │ │ │
├── Debugger (DAP, DWARF) │ │ │ │ │
└── Optimizasyonlar │ │ │ │ │
│ │ │ │ │
┌────────────────────────────────────────┘ │ │ │ │
│ │ │ │ │
└── Proje Sistemi / Build Tooling ─────────────┘ │ │ │
│ │ │ │
├── saqut init, saqut build, saqut test │ │ │
├── Paket Yöneticisi │ │ │
└── Derleyici Konfigürasyonu (CompilerConfig) │ │ │
│ │ │
┌────────────────────────────────────────────────────────────┘ │ │
│ │ │
└── LSP Sunucusu (JSON-RPC) ───────────────────────────────────────┘ │
│ │
├── VSCode Eklentisi │
├── Diğer IDE Desteği (Neovim, JetBrains, Emacs...) │
└── Debug Adapter Protocol (DAP) │
```
> **Okuma rehberi:** Yukarı ı ı ı ı ı ı ı
---
# Aşama 0: Metadata ve Konum Takibi (Derleyici Katmanı
> **Ön Koşul:** Yok. Mevcut kod tabanı
> **Hedef:** Her token ve AST düğümü kaynak koddaki konumunu bilsin. Hata mesajları ı
> **Neden bu aşama ilk?** LSP dahil tüm geliştirici deneyimi özellikleri, konum bilgisine bağı ı ı
### Issue 0.1: `SourceFile` ve `SourceLocation` Yapı ı ı ı
- **Dosya:** `src/core/location.hpp` (yeni)
- **Yapı
- `SourceLocation` yapı ı `fileId` (string), `line` (1 tabanlı `column` (1 tabanlı `offset` (0 tabanlı
- `SourceFile` sı ı ı ı ı ı
- `offsetToLocation(offset) -> SourceLocation` metodu: Binary search ile offset'i satı
- `locationToOffset(SourceLocation) -> int` metodu: Satı
- **Test kriteri:** `SourceFile("a\nbc\n")` için offset 2'nin `{line:2, column:1}` olduğunu doğrula.
### Issue 0.2: Lexer'a Satı
- **Dosya:** `src/lexer/lexer.hpp`
- **Yapı
- `Lexer` sı ı ı `currentLine` , `currentColumn` üye değişkenleri ekle.
- `nextChar()` çağrı ı ı `'\n'` görürse satı ı ı ı ı
- `skipWhiteSpace()` içinde de satı ı ı
- Mevcut konumu `SourceLocation` olarak döndüren `getLocation()` metodu ekle.
- `INumber` yapı ı `startLoc` ve `endLoc` alanları `readNumeric()` bu alanları
- **Test kriteri:** `"1 + 2"` tarandı ı `1` token'ı ı `{line:1, column:1}` olmalı
### Issue 0.3: Token'lara ve AST Düğümlerine Konum Bilgisi Ekle
- **Dosyalar:** `src/tokenizer/token.hpp` , `src/parser/ast.hpp`
- **Yapı
- `Token` temel sı ı ı `SourceLocation loc` ekle. `start` /`end` offset'lerini kaldı ı `loc` kullan).
- `ParserToken` yapı ı `SourceLocation loc` ekle, `parseToken()` içinde token'dan kopyala.
- `ASTNode` temel sı ı ı `SourceLocation loc` ekle. Her düğüm oluşturulurken ilgili token'ı
- **Test kriteri:** `saqut tokens source.sqt` çı ı ı ı
---
# Aşama 1: Sembol Tablosu ve Tip Sisteminin Temelleri (Derleyici Katmanı ı
> **Ön Koşul:** Aşama 0 tamamlanmı ı
> **Hedef:** Derleyici, kodda tanı
### Issue 1.1: Sembol ve Sembol Tablosu Sı ı ı ı
- **Dosya:** `src/symbol/symbol.hpp` , `src/symbol/symbol_table.hpp` (yeni)
- **Yapı
- `Symbol` yapı ı `name` (string), `kind` (enum: Variable, Function, Struct, Parameter), `type` (`Type*`), `definitionLoc` (SourceLocation), `references` (vector< SourceLocation > ).
- `SymbolTable` sı ı ı `enterScope()` , `exitScope()` , `define(name, Symbol)` , `resolve(name) -> Symbol*` , `addReference(name, location)` .
- Scope chain: Global → Function → Block. İsim çözümleme en iç scope'tan dı
- **Test kriteri:** İç içe bloklarda aynı ı ı
### Issue 1.2: Tip Sistemi Temellerini Kur
- **Dosya:** `src/symbol/type.hpp` (yeni)
- **Yapı
- `Type` soyut sı ı ı ı ı ı `PrimitiveType` (Int, Float, Bool, Char, String, Void), `StructType` , `FunctionType` (parametre tipleri + dönüş tipi), `ArrayType` .
- Tip eşitliği kontrolü (`equals` metodu).
- Tip uyumluluğu (atama için implicit cast kuralları
- **Test kriteri:** `int x = "hello";` için "tip uyuşmazlı ı ı ı ı
### Issue 1.3: Sembol Toplayı ı ı
- **Dosya:** `src/symbol/symbol_collector.hpp` (yeni, mevcut `json.hpp` içindeki `collectSymbols` kaldı ı
- **Yapı
- `SymbolCollector` sı ı ı `ASTNode` ziyaretçisi. AST'yi dolaşı
- `FunctionDecl` → `SymbolTable::define(name, FunctionSymbol)`
- `VariableDecl` → `SymbolTable::define(name, VariableSymbol)` , tipini `Type` sisteminden çözümle.
- `Identifier` referansları `SymbolTable::addReference(name, loc)`
- `StructDecl` → `SymbolTable::define(name, StructSymbol)`
- Ziyaret sı ı ı ı ı ı ı
- **Test kriteri:** `saqut symbols source.sqt` çı ı ı `SymbolTable` 'dan gelen tam veriyi JSON olarak göstersin.
---
# Aşama 2: Temel LSP Altyapı ı ı `lsp` modu)
> **Ön Koşul:** Aşama 0 ve Aşama 1 tamamlanmı ı
> **Hedef:** VSCode içinde `.sqt` dosyaları ı ı
### Issue 2.1: JSON-RPC 2.0 Altyapı ı ı
- **Dosya:** `src/lsp/json_rpc.hpp` (yeni)
- **Yapı
- `JsonRpcMessage` yapı ı `jsonrpc` , `id` , `method` , `params` alanları
- `parseMessage(string) -> JsonRpcMessage` fonksiyonu: Ham stdin girdisini JSON-RPC mesajı
- `serializeMessage(JsonRpcMessage) -> string` fonksiyonu: Cevap mesajı ı ı
- Content-Length header'ı ı
- **Test kriteri:** El ile gönderilen `{"jsonrpc":"2.0","id":1,"method":"initialize","params":{...}}` mesajı
### Issue 2.2: `saqut lsp` Komutunu Ekle
- **Dosya:** `src/cli/commands/lsp.hpp` (yeni), `main.cpp` 'ye kayı
- **Yapı
- `cmdLsp` fonksiyonu: stdin/stdout'tan JSON-RPC mesajları ı
- Ana döngü: `initialize` → `initialized` → `textDocument/didOpen` , `didChange` , `definition` , `hover` ...
- `shutdown` ve `exit` mesajları ı
- **Test kriteri:** `saqut lsp` process'i başlatı ı ı `initialize` isteğine `capabilities` ile cevap versin.
### Issue 2.3: Artı ı
- **Dosya:** `src/lsp/project_manager.hpp` (yeni)
- **Yapı
- `ProjectManager` sı ı ı ı ı ı ı ı
- `didOpen` / `didChange` ile dosya içeriği güncellendiğinde sadece o dosyayı
- Hata listesini (diagnostics) güncelle.
- **Test kriteri:** Bir dosyada değişiklik yapı ı ı ı ı
### Issue 2.4: İlk LSP Yeteneklerini Uygula
- **Dosya:** `src/lsp/handlers/` (yeni dizin)
- **Yapı
- `textDocument/publishDiagnostics` : Sembol toplayı ı ı ı
- `textDocument/definition` : İmleç konumundaki sembolü bul, tanı ı ı `SourceLocation` 'ı
- `textDocument/documentSymbol` : Dosyadaki tüm sembolleri hiyerarşik olarak listele.
- `textDocument/hover` : İmleç altı ı ı ı
- **Test kriteri:** VSCode'da `.sqt` dosyası ı ı ı ı ı ı ı ı
---
# Aşama 3: Syntax Highlighting (TextMate + Semantik)
> **Ön Koşul:** TextMate için: sadece keyword listesi (hemen yapı
> **Hedef:** `.sqt` dosyaları ı
### Issue 3.1: TextMate Dilbilgisi Dosyası
- **Dosya:** `editors/vscode/syntaxes/saqut.tmLanguage.json` (yeni)
- **Yapı
- Keyword'ler, operatörler, sayı ı ı
- Mevcut `keywords[]` dizisindeki tüm keyword'leri kapsa.
- String interpolation (ileride) için temel yapı
- **Test kriteri:** VSCode'da `.sqt` dosyası ı ı ı `if` , `for` mavi, `"hello"` turuncu, `// yorum` yeşil görünsün.
### Issue 3.2: Semantik Token Desteği Ekle
- **Dosya:** `src/lsp/handlers/semantic_tokens.hpp` (yeni)
- **Yapı
- `textDocument/semanticTokens/full` isteğini işle.
- AST + Sembol Tablosu kullanarak her token için `tokenType` (function, variable, parameter, type, keyword) ve `tokenModifiers` (declaration, readonly, static) belirle.
- LSP semantic token delta formatı
- **Test kriteri:** VSCode'da `int x = foo();` yazı ı ı `x` (değişken) ile `foo` (fonksiyon) farklı
---
# Aşama 4: Kod Biçimlendirici ve Dokümantasyon Üretici (Derleyici Katmanı
> **Ön Koşul:** Aşama 0, Aşama 1. (AST ve konum bilgisi yeterli)
> **Hedef:** `saqut fmt` ile otomatik formatlama, `saqut doc` ile dokümantasyon üretimi.
### Issue 4.1: Pretty Printer (Kod Biçimlendirici)
- **Dosya:** `src/tools/pretty_printer.hpp` (yeni)
- **Yapı
- AST'yi dolaşarak, standart girintileme ve boşluk kuralları
- `saqut fmt <dosya>` komutu: dosyayı ı
- Kural seti: 4 boşluk girinti, operatör etrafı ı ı
- **Test kriteri:** `saqut fmt source.sqt` çalı ı ı ı ı ı ı ı
### Issue 4.2: Dokümantasyon Üretici
- **Dosya:** `src/tools/doc_generator.hpp` (yeni)
- **Yapı
- `///` veya `/** */` ile başlayan yorum blokları ı ı ı ı
- `saqut doc <dosya>` komutu: Markdown formatı
- LSP `hover` isteğine bu dokümantasyonu ekle (zengin Markdown).
- **Test kriteri:** `/// Bu fonksiyon iki sayı ı yorumu, `int add(int a, int b)` için hover'da görünsün.
---
# Aşama 5: IR Güçlendirme ve Interpreter (Derleyici Katmanı
> **Ön Koşul:** Aşama 1 (Sembol Tablosu ve Tip Sistemi).
> **Hedef:** Yazı ı ı ı
### Issue 5.1: IR'ye Kontrol Akı ı ı
- **Dosya:** `src/ir/ir.hpp`
- **Yapı
- `OPCode` enum'una ekle: `br` (koşulsuz dal), `br_eq` , `br_lt` , `br_gt` (koşullu dal), `cmp` (karşı ı `call` , `ret` , `param` , `load` , `store` , `alloca` .
- `IROpData` yapı ı ı ı
- `CodeGenerator` sı ı ı `if` , `while` , `for` , `do-while` , fonksiyon çağrı ı ı ı ı
- **Test kriteri:** `if (x < 5) return x;` kodu için `cmp` , `br_lt` , `ret` IR komutları
### Issue 5.2: Interpreter (Sanal Makine)
- **Dosya:** `src/backend/interpreter.hpp` (yeni)
- **Yapı
- `Interpreter` sı ı ı ı ı ı
- Sanal register'ları
- `OPCode` başı ı ı
- `saqut run <dosya>` komutu: Interpreter'ı ı ı
- `saqut` (argümansı ı ı ı
- **Test kriteri:** `int main() { return 42; }` kodu çalı ı ı ı ı ı ı
### Issue 5.3: C Transpile Backend
- **Dosya:** `src/backend/transpile_c.hpp` (yeni)
- **Yapı
- `CTranspiler` sı ı ı ı ı
- `saqut transpile <dosya> -o output.c` komutu.
- Üretilen C kodu `gcc` /`clang` ile derlenebilir ve çalı ı ı ı
- `#line` direktifleri ile orijinal kaynak koda geri referans ver.
- **Test kriteri:** `int main() { return 1+2; }` kodu C'ye çevrilip GCC ile derlendiğinde çalı ı ı
---
# Aşama 6: Debugger (DAP Tabanlı
> **Ön Koşul:** Aşama 5 (Interpreter).
> **Hedef:** VSCode içinden breakpoint koyma, adı ı ı ı
### Issue 6.1: Debug Adapter Protocol (DAP) Altyapı ı
- **Dosya:** `src/debug/dap_server.hpp` (yeni)
- **Yapı
- JSON-RPC üzerine DAP mesajları ı ı ı
- `saqut debug` komutu: DAP sunucusunu başlatı
- `launch` ve `attach` isteklerini işle.
- **Test kriteri:** VSCode'dan "Debug" başlatı ı ı ı ı ı ı ı
### Issue 6.2: Interpreter'a Debugging Yetenekleri Ekle
- **Dosya:** `src/backend/interpreter.hpp` (güncelle)
- **Yapı
- Interpreter'a `stepOver` , `stepInto` , `stepOut` , `pause` , `continue` yetenekleri.
- Breakpoint yönetimi: `SourceLocation` ile eşleşen satı
- Değişken değerlerini okuma: `stackFrame` 'den sembol ismiyle değer bulma.
- `variables` ve `evaluate` isteklerini cevapla.
- **Test kriteri:** VSCode'da bir satı ı ı ı ı
### Issue 6.3: Zaman Yolculuğu Debugging (Opsiyonel, İleri Seviye)
- **Dosya:** `src/debug/time_travel.hpp` (yeni)
- **Yapı
- Interpreter her adı
- Geri adı
- `saqut debug --time-travel` ile açı ı
- **Test kriteri:** Debug sı ı ı ı ı ı
---
# Aşama 7: Gelişmiş LSP Yetenekleri (Derleyici Katmanı
> **Ön Koşul:** Aşama 1, Aşama 5 (Interpreter çalı ı ı
> **Hedef:** VSCode'da tam kod tamamlama, referans bulma, kod haritası
### Issue 7.1: Kod Tamamlama (Completion)
- **Dosya:** `src/lsp/handlers/completion.hpp`
- **Yapı
- `textDocument/completion` isteğini işle.
- İmleç konumundaki scope'a göre görünür tüm sembolleri listele.
- Fonksiyon parametre bilgisi (signature help).
- **Test kriteri:** `x.` yazı ı ı `x` 'in struct üyeleri listelensin.
### Issue 7.2: Referans Bulma (Find References)
- **Dosya:** `src/lsp/handlers/references.hpp`
- **Yapı
- `textDocument/references` isteğini işle.
- Sembol tablosundan sembolün tüm referans konumları ı
- **Test kriteri:** Bir değişkene sağ tı ı ı
### Issue 7.3: Kod Haritası ı
- **Dosya:** `src/lsp/handlers/call_hierarchy.hpp`
- **Yapı
- `textDocument/prepareCallHierarchy` , `callHierarchy/incomingCalls` , `callHierarchy/outgoingCalls` isteklerini işle.
- AST ve Sembol Tablosu'ndan çağrı ı
- **Test kriteri:** Bir fonksiyona sağ tı ı ı ı
---
# Aşama 8: Optimizasyonlar ve Analiz Araçları
> **Ön Koşul:** Aşama 5 (IR ve Interpreter).
> **Hedef:** Kod kalitesini artı
### Issue 8.1: Linter ve Statik Analiz
- **Dosya:** `src/tools/linter.hpp`
- **Yapı
- `saqut lint <dosya>` komutu.
- Kullanı
- Karmaşı ı
- Null olabilecek değerlere erişim kontrolü (basit veri akı ı
- **Test kriteri:** Kullanı `[WARN] Unused variable 'x' at line 5` çı ı ı ı ı
### Issue 8.2: Optimizasyon Pas'ları
- **Dosya:** `src/optimizer/optimizer.hpp` , `src/optimizer/passes/`
- **Yapı
- Constant folding: `4 + 1` → `5` .
- Dead code elimination: `if (false) { ... }` bloğunu sil.
- Unused variable elimination: Kullanı ı ı ı ı
- `CompilerConfig` ile her pas açı ı ı ı
- **Test kriteri:** `--opt-all` ile çalı ı ı
### Issue 8.3: Performans Profili (Profiler)
- **Dosya:** `src/tools/profiler.hpp`
- **Yapı
- `saqut profile run <dosya>` komutu.
- Interpreter modunda her fonksiyon çağrı ı ı
- Sonuçları ı ı
- **Test kriteri:** Profiler çı ı ı
---
# Aşama 9: Proje Sistemi, Derleyici Konfigürasyonu ve Feature Toggle
> **Ön Koşul:** Aşama 5 (Interpreter), Aşama 8 (Optimizasyon altyapı ı
> **Hedef:** `saqut init` , `saqut build` , `saqut test` komutları ı ı ı
### Issue 9.1: Proje Başlatma ve Build Sistemi
- **Dosya:** `src/cli/commands/init.hpp` , `src/cli/commands/build.hpp`
- **Yapı
- `saqut init <proje-adı : Standart dizin yapı ı `saqut.json` (proje manifesti) oluştur.
- `saqut build` : Manifest'i oku, tüm kaynak dosyaları ı ı ı
- **Test kriteri:** `saqut init myapp && cd myapp && saqut build` ile çalı
### Issue 9.2: CompilerConfig ve Feature Toggle
- **Dosya:** `src/core/compiler_config.hpp`
- **Yapı
- `CompilerConfig` yapı ı `enableFor` , `enableClass` ...), optimizasyon pas'ları ı ı ı
- `saqut` komut satı ı `--disable-while` , `--skip-constant-folding` gibi bayraklarla konfigüre edilebilsin.
- Tokenizer ve Parser, `CompilerConfig` 'e göre davranı ı ı ı
- **Test kriteri:** `saqut run --disable-while` ile while döngüsü içeren kod hata versin.
### Issue 9.3: Test Çerçevesi (Built-in)
- **Dosya:** `src/cli/commands/test.hpp` , `src/core/test_framework.hpp`
- **Yapı
- `test` anahtar kelimesi veya `#[test]` anotasyonu.
- `saqut test` komutu: Projedeki tüm test fonksiyonları ı ı ı ı
- Test sonuçları ı ı ı
- **Test kriteri:** `test "iki kere iki dort" { assert(2*2 == 4); }` testi `saqut test` ile geçsin.
---
# Aşama 10: Paket Yöneticisi ve Dağı ı
> **Ön Koşul:** Aşama 9 (Proje sistemi).
> **Hedef:** Harici kütüphaneleri projeye ekleme ve dilin resmi paket kaydı
### Issue 10.1: Paket Yöneticisi (saqut add)
- **Dosya:** `src/cli/commands/add.hpp` , `src/package/registry.hpp`
- **Yapı
- `saqut add <paket-adi>` : Merkezi paket kaydı ı `saqut.json` 'a ekle.
- Bağı ı ı
- **Test kriteri:** `saqut add json` ile JSON kütüphanesi projeye eklensin ve `import json;` kullanı
### Issue 10.2: Kendi Kendini Derleme (Self-Hosting)
- **Dosya:** Proje geneli.
- **Yapı
- saQut derleyicisinin kaynak kodu, saQut dilinde yazı
- Bu, dilin olgunluğunun nihai testidir.
- **Test kriteri:** `saqut build` ile derleyici kendi kaynak kodunu derleyip çalı
---
# Aşama 11: Dil Spesifikasyonu ve Resmi Dokümantasyon
> **Ön Koşul:** Aşama 9 (dil özellikleri stabilize olmalı
> **Hedef:** Geliştiricilerin referans alabileceği eksiksiz bir dil tanı ı
### Issue 11.1: Dil Spesifikasyonu Yaz
- **Dosya:** `docs/lang_spec.md` (kitap formatı
- **Yapı
- Sözdizimi grameri (EBNF).
- Tip sistemi ve dönüşüm kuralları
- Çalı ı ı ı
- Standart kütüphane sözleşmeleri.
- **Test kriteri:** Spesifikasyon, tüm dil özelliklerini kapsası ı ı ı
### Issue 11.2: Resmi Web Sitesi ve Öğretici
- **Dosya:** `docs/website/`
- **Yapı
- saqut-lang.org için statik site.
- "Başlangı ı ı ı ı
- **Test kriteri:** Site yayı ı ı ı
---
# Ek: VSCode Eklentisi Paketleme
> **Ön Koşul:** Aşama 3 (Syntax Highlighting), Aşama 4 (LSP handlers).
> **Hedef:** VSCode marketplace'te yayı
### Issue E.1: VSCode Eklenti Manifesti ve Paketleme
- **Dosya:** `editors/vscode/package.json` , `editors/vscode/extension.js`
- **Yapı
- `package.json` içinde `activationEvents` , `contributes.languages` , `contributes.commands` tanı
- `extension.js` : LSP sunucusunu (`saqut lsp`) başlat, dil konfigürasyonunu yükle.
- `.vsix` paketi oluşturma betiği.
- **Test kriteri:** Eklenti VSCode'a yüklendiğinde `.sqt` dosyaları ı ı ı ı
---
> **Yol haritası Her aşamadaki issue'lar sı ı ı ı ı
saqut