[Fikir] CLI Komut Seti — Tam Araç Zinciri Vizyonu (Tier 0-3: check/fmt/test/repl/build/pkg/...) #107

New Issue

saqut · 2026-06-14T22:26:30+03:00

saqut commented

2026-06-14 22:26:30 +03:00

Giriş (Nedir, Neden Önemli?)

Bu issue'nun ilk hâli sadece 3 ek komut (check, explain, watch) öneriyordu — ama soru aslında "derleyici tamamen bittiğinde saqut komutu ne kadar geniş bir araç haline gelmeli?" Bu revizyon, CLI'yı tek seferde değil, katmanlı (tier) bir yol haritası olarak ele alır: hangi komutlar "olmazsa olmaz" (v0/v1), hangileri "dil tamamlandıktan sonra doğal sonraki adım" (v1.5-v2), hangileri "uzak gelecek/ekosistem" (v2+).

Ortak ilke: her komut aynı bayrak ailesini paylaşmalı — --format=json|tree|dot|table (#106), --optimized, --color, tutarlı çıkış kodları (exit code: 0=başarı, 1=derleme hatası, 2=kullanım hatası). Bu tutarlılık olmadan her yeni komut CLI'yı parçalı hissettirir.

Tier 0 — Çekirdek / Bugün Var veya Faz 0-4 Kapsamında (olmazsa olmaz)

Komut	Durum	Not
`saqut tokens`	✅ var
`saqut ast`	✅ var	`--format`/`--optimized` ile genişler (#106)
`saqut symbols`	🚧 Faz 2
`saqut ir`	🚧 ileride	#75
`saqut run`	🚧 IR+VM	ADR-015
`saqut check`	yeni, ucuz	Faz 0 biter bitmez bedavaya gelir — sadece `DiagnosticEngine` çalıştırır, çalıştırmaz

Tier 1 — Dil/Derleyici Tamamlandığında "Eksikse Eksik Hissedilir"

Komut	Açıklama
`saqut fmt`	(#93) Kod biçimlendirici — formatter olmayan bir 2020'ler dili "eksik" sayılır
`saqut test`	(#96) Dil-içi `test{}` bloklarını çalıştırır, özet rapor (`X geçti, Y kaldı`)
`saqut explain <kod>`	Hata kodu açıklaması (örn. `E003`) + örnek doğru/yanlış kod + ilgili ADR linki
`saqut repl`	Argümansız `saqut` çağrısı → etkileşimli kabuk (satır satır ifade değerlendirme, `print` sonucu hemen görünür)
`saqut lsp`	(#91) Dil sunucusu — editör entegrasyonunun kapısı
`saqut watch <file> [--run\|--check]`	Dosya değiştikçe otomatik yeniden çalıştırma

Tier 2 — Modül Sistemi + Ekosistem Olgunlaştıkça (v1.5-v2)

Komut	Açıklama
`saqut build <entry> -o <out>`	(#81-83 modül sistemi sonrası) Çoklu dosyalı projeyi tek bir IR/bytecode paketine derler — "derleme çıktısı" kavramının netleşmesi
`saqut doc <dir>`	Struct/fonksiyon üstündeki yorumlardan otomatik dokümantasyon (Markdown/HTML) üretir — `saqut fmt`'in yorum-koruma çözümüne (#93) bağımlı
`saqut bench <file>`	Bir `test{}` bloğunu veya fonksiyonu N kez çalıştırıp süre/iterasyon raporu verir — VM'in "incelenebilir" felsefesiyle iyi örtüşür (her adımın zamanlaması)
`saqut fix <file>`	`--apply` ile bazı diagnostic'leri (örn. kullanılmayan değişkeni silme `W001`, eksik `return` ekleme) otomatik düzeltir — #98 "akıllı diagnostic"in eylem hâli
`saqut trace`/`saqut replay`	(#94) Zaman-yolculuğu hata ayıklama dosyalarını üretir/oynatır
`saqut pkg ...`	(#97) Paket yöneticisi alt-komutları — `pkg add`, `pkg list`

Tier 3 — Uzak Gelecek / Vitrin

Komut	Açıklama
`saqut wasm <file> -o <out.wasm>`	(#95) Playground/tarayıcı hedefi
`saqut profile <file>`	IR seviyesinde sıcak-yol (hot path) analizi — VM trace altyapısına (#94) dayanır

Açık Sorular

saqut repl (Tier 1), VM'in adım-adım çalışabilmesini gerektirir — bu, IR/VM tasarımının (#74-78) "her ifade tek başına değerlendirilebilir mi" sorusunu erkene çeker. REPL'siz bir dil 2020'lerde eksik hissedilir; bu yüzden Tier 1'de.
saqut build (Tier 2) çıkış formatı ne olacak — kendi bytecode formatı mı, yoksa C transpile (ikinci backend, ADR-006/008) çıktısı + sistem derleyicisiyle native binary mi? İki farklı "build" hedefi olabilir: --target=bytecode (varsayılan, hızlı) ve --target=c (taşınabilir/native, ADR-008).
Her komutun --help çıktısı ve hata mesajları tutarlı bir üslupla mı yazılacak — bu, #110'daki "Go tarzı modernlik" tavsiyesiyle doğrudan bağlantılı.

İmza/Yorum: Önceki hâlinde sadece 3 komut önerilmişti; bu revizyon CLI'yı "derleyici bittiğinde elimizde ne olacak" sorusuna tam bir araç zinciri olarak cevap veriyor. Tier sınırları kesin değil — her faz bittiğinde bu tablo gözden geçirilmeli.

### Giriş (Nedir, Neden Önemli?) Bu issue'nun ilk hâli sadece 3 ek komut (`check`, `explain`, `watch`) öneriyordu — ama soru aslında "**derleyici tamamen bittiğinde** `saqut` komutu ne kadar geniş bir araç haline gelmeli?" Bu revizyon, CLI'yı **tek seferde** değil, **katmanlı (tier) bir yol haritası** olarak ele alır: hangi komutlar "olmazsa olmaz" (v0/v1), hangileri "dil tamamlandıktan sonra doğal sonraki adım" (v1.5-v2), hangileri "uzak gelecek/ekosistem" (v2+). Ortak ilke: **her komut aynı bayrak ailesini paylaşmalı** — `--format=json|tree|dot|table` (#106), `--optimized`, `--color`, tutarlı çıkış kodları (exit code: `0`=başarı, `1`=derleme hatası, `2`=kullanım hatası). Bu tutarlılık olmadan her yeni komut CLI'yı parçalı hissettirir. --- ### Tier 0 — Çekirdek / Bugün Var veya Faz 0-4 Kapsamında (olmazsa olmaz) | Komut | Durum | Not | |---|---|---| | `saqut tokens` | ✅ var | | | `saqut ast` | ✅ var | `--format`/`--optimized` ile genişler (#106) | | `saqut symbols` | 🚧 Faz 2 | | | `saqut ir` | 🚧 ileride | #75 | | `saqut run` | 🚧 IR+VM | ADR-015 | | `saqut check` | yeni, ucuz | Faz 0 biter bitmez bedavaya gelir — sadece `DiagnosticEngine` çalıştırır, çalıştırmaz | ### Tier 1 — Dil/Derleyici Tamamlandığında "Eksikse Eksik Hissedilir" | Komut | Açıklama | |---|---| | `saqut fmt` | (#93) Kod biçimlendirici — formatter olmayan bir 2020'ler dili "eksik" sayılır | | `saqut test` | (#96) Dil-içi `test{}` bloklarını çalıştırır, özet rapor (`X geçti, Y kaldı`) | | `saqut explain <kod>` | Hata kodu açıklaması (örn. `E003`) + örnek doğru/yanlış kod + ilgili ADR linki | | `saqut repl` | Argümansız `saqut` çağrısı → etkileşimli kabuk (satır satır ifade değerlendirme, `print` sonucu hemen görünür) | | `saqut lsp` | (#91) Dil sunucusu — editör entegrasyonunun kapısı | | `saqut watch <file> [--run\|--check]` | Dosya değiştikçe otomatik yeniden çalıştırma | ### Tier 2 — Modül Sistemi + Ekosistem Olgunlaştıkça (v1.5-v2) | Komut | Açıklama | |---|---| | `saqut build <entry> -o <out>` | (#81-83 modül sistemi sonrası) Çoklu dosyalı projeyi tek bir IR/bytecode paketine derler — "derleme çıktısı" kavramının netleşmesi | | `saqut doc <dir>` | Struct/fonksiyon üstündeki yorumlardan otomatik dokümantasyon (Markdown/HTML) üretir — `saqut fmt`'in yorum-koruma çözümüne (#93) bağımlı | | `saqut bench <file>` | Bir `test{}` bloğunu veya fonksiyonu N kez çalıştırıp süre/iterasyon raporu verir — VM'in "incelenebilir" felsefesiyle iyi örtüşür (her adımın zamanlaması) | | `saqut fix <file>` | `--apply` ile bazı diagnostic'leri (örn. kullanılmayan değişkeni silme `W001`, eksik `return` ekleme) otomatik düzeltir — #98 "akıllı diagnostic"in eylem hâli | | `saqut trace`/`saqut replay` | (#94) Zaman-yolculuğu hata ayıklama dosyalarını üretir/oynatır | | `saqut pkg ...` | (#97) Paket yöneticisi alt-komutları — `pkg add`, `pkg list` | ### Tier 3 — Uzak Gelecek / Vitrin | Komut | Açıklama | |---|---| | `saqut wasm <file> -o <out.wasm>` | (#95) Playground/tarayıcı hedefi | | `saqut profile <file>` | IR seviyesinde sıcak-yol (hot path) analizi — VM trace altyapısına (#94) dayanır | --- ### Açık Sorular - `saqut repl` (Tier 1), VM'in **adım-adım** çalışabilmesini gerektirir — bu, IR/VM tasarımının (#74-78) "her ifade tek başına değerlendirilebilir mi" sorusunu erkene çeker. REPL'siz bir dil 2020'lerde eksik hissedilir; bu yüzden Tier 1'de. - `saqut build` (Tier 2) çıkış formatı ne olacak — kendi bytecode formatı mı, yoksa C transpile (ikinci backend, ADR-006/008) çıktısı + sistem derleyicisiyle native binary mi? İki farklı "build" hedefi olabilir: `--target=bytecode` (varsayılan, hızlı) ve `--target=c` (taşınabilir/native, ADR-008). - Her komutun `--help` çıktısı ve hata mesajları **tutarlı bir üslupla** mı yazılacak — bu, #110'daki "Go tarzı modernlik" tavsiyesiyle doğrudan bağlantılı. *İmza/Yorum:* Önceki hâlinde sadece 3 komut önerilmişti; bu revizyon CLI'yı "derleyici bittiğinde elimizde ne olacak" sorusuna **tam bir araç zinciri** olarak cevap veriyor. Tier sınırları kesin değil — her faz bittiğinde bu tablo gözden geçirilmeli.

saqut added the

fikir

cli-ux

labels 2026-06-14 22:26:30 +03:00

saqut changed title from ~~[Fikir] CLI Komut Seti Genişletme Önerileri (`check`, `explain`, `watch`)~~ to [Fikir] CLI Komut Seti — Tam Araç Zinciri Vizyonu (Tier 0-3: check/fmt/test/repl/build/pkg/...)

2026-06-14 22:37:45 +03:00

saqut referenced this issue

2026-06-14 22:37:46 +03:00

[Fikir] LSP Sunucusu — Derleyici Tamamlandığında Tam Yetenek Haritası (Tier 1-4) #91

saqut referenced this issue

2026-06-14 22:38:39 +03:00

[Fikir] v1 → v2 Ekosistem Yol Haritası — Derleyici Bittikten Sonraki Bağımlılık Sırası #111

Sign in to join this conversation.