Genel bakış ve temel kavramlar
CleanLens ne yapar, hangi sorunu çözer ve diğer tüm dokümanlarda kullanılan terimler
CleanLens nedir
CleanLens, yerel çalışan ve Git geçmişini anlayan bir Clean Code analizörüdür. Tek bir motoru paylaşan iki biçimde çalışır:
- bir VS Code eklentisi (kenar çubuğu, pano webview'u, satır içi tanılar) ve
- bir
cleanlenskomut satırı aracı (metin, Markdown veya JSON rapor, CI kapısı).
JavaScript / TypeScript (.js .jsx .mjs .cjs .ts .tsx) ve Python (.py) dosyalarını yapılandırılabilir 14 kurala göre analiz eder, ardından her sorunu hangi geliştiricinin eklediğini bulur ve her geliştiriciye 0–100 arası bir Clean Code Score verir.
Her şey sizin makinenizde çalışır. Ağ isteği yapmaz, telemetri toplamaz ve oturum açma gerektirmez (bkz. PRIVACY.md).
Çözdüğü sorun
"Kötü kodu kim yazdı" araçlarının çoğu mevcut dosyalar üzerinde git blame kullanır. Bu adil değildir: Ayşe 2.000 satırlık eski bir dosyada tek bir satırı düzenlerse, blame onu bu dosyanın son yazarı yapar ve dosya düzeyinde çalışan bir araç dosyanın eski sorunlarını ona yükler.
CleanLens bunun yerine commit geçmişini yeniden oynatır. Her commit için değişen her dosyayı commit'ten önce ve sonra analiz eder ve iki ihlal kümesini karşılaştırır:
- yalnızca commit'ten sonra, commit'in değiştirdiği satırlarda görünen bir ihlal → o commit'in yazarı tarafından eklenmiştir (introduced);
- önce ve sonra var olan bir ihlal → mevcuttur (existing), kimseye yazılmaz;
- önce var olup sonra kaybolan bir ihlal → düzeltilmiştir (fixed), yazarın hanesine artı olarak yazılır.
Puanlar ham sayılara değil, bir geliştiricinin yazdığı her 1.000 satırda eklediği sorun miktarına dayanır. İstatistiksel bir düzeltme (Bayesçi büzülme), küçük bir örneklemin aşırı bir puan üretmesini engeller.
Tasarım ilkeleri
- Kolaylıktan önce adalet. Bir geliştiriciye yalnızca kanıt varsa (yüksek veya orta güven) ihlal yazılır. Belirsiz olan her şey gösterilir ama puana katılmaz.
- Kalite hacimden ayrıdır. "Katkı %" (ne kadar kod yazdığınız) her zaman puanın yanında gösterilir ve asla puana karıştırılmaz.
- Yerel ve gizli. Yalnızca
gitalt süreçleri ve dosya okuma. Sunucu yok. - Yapılandırılabilir. Kurallar, önem dereceleri, sınırlar, hariç tutmalar, puanlama sabitleri, kimlikler ve geçmiş derinliği ayarlanabilir (bkz. 10 — Yapılandırma başvurusu ve 11 — Özelleştirme kılavuzu).
- Tek motor, iki arayüz. Eklenti ve CLI aynı
analyzeRepository()fonksiyonunu çağırır; bu yüzden sayıları her zaman aynıdır.
Sözlük
Bu terimler tüm dokümanlarda ve arayüzde kullanılır.
| Terim | Anlamı |
|---|---|
| Kural (Rule) | 14 denetimden biri, örn. maxFunctionLines. enabled, severity ve isteğe bağlı olarak limit / options ile yapılandırılır. |
Bulgu (RawFinding) | Bir analizörün döndürdüğü şey: kural kimliği, dosya, satır aralığı, mesaj, isteğe bağlı sembol adı. |
| İhlal (Violation) | Önem derecesi, kategori, ağırlık ve sabit bir kimlikle zenginleştirilmiş bulgu. |
| Önem derecesi (Severity) | low, medium, high, critical. İhlalin ağırlığını belirler (varsayılan 1 / 3 / 5 / 8). |
| Kategori | Her kural üç puanlama kategorisinden birine aittir: duplication (tekrar), structure (yapı), hygiene (hijyen). |
| Ağırlıklı puan | Bir ihlal kümesinin önem ağırlıklarının toplamı. |
| KLOC | 1.000 satır kod. Yoğunluklar "KLOC başına ağırlıklı puan" olarak ölçülür. |
| Analiz edilen satırlar | Bir geliştiricinin analiz edilen commit'lerde, analiz edilebilir dosyalarda eklediği veya değiştirdiği satırlar. |
| Parmak izi (Fingerprint) | Kural + yol + sembol + normalleştirilmiş kod bağlamının hash'i. Satır numarası kaysa bile iki dosya sürümünde "aynı ihlali" tanır. |
| Atama durumu | introduced, existing, fixed, excluded, unattributed. Bkz. 07. |
| Atama güveni | high, medium, low: motorun, ihlale yazarın neden olduğundan ne kadar emin olduğu. Yalnızca high/medium puanı etkiler. |
| Puan güven seviyesi | insufficient, provisional, reliable, highly_reliable: puanın ne kadar koda dayandığı. |
| Sıralanabilir (Rankable) | Geliştiricinin sıralamada yer alacak kadar (varsayılan ≥ 1.000) analiz edilen satırı olup olmadığı. |
| Net kalite etkisi | Eklenen ağırlıklı puanlar eksi düzeltilen ağırlıklı puanlar. Yalnızca gösterim içindir. |
| HEAD taraması | Çalışma ağacındaki mevcut dosyaların analizi. İhlal listesini üretir. |
| Commit yürüyüşü | Birleştirme olmayan en yeni N commit'in yeniden oynatılması. Atamayı ve puanları üretir. |
| Ön ayar (Preset) | Başlangıç kural yapılandırması: javascript, react, python, django. |
Bir çalıştırmadan ne elde edersiniz
- Proje toplamları: geliştiriciler, ihlaller, atanamayan ihlaller, analiz edilen dosyalar, analiz edilen commit'ler, zaman damgası.
- Geliştirici başına: Clean Code Score ve üç alt puanı, analiz edilen satırlar, puan güveni, katkı %, yeni / düzeltilen / mevcut / atanamayan sayıları, ağırlıklı puanlar, net kalite etkisi, KLOC başına yoğunluk, aktif günler, ilk/son katkı, e-postalar.
- İhlal başına: önem derecesi, kural, mesaj, dosya ve satır aralığı, durum, güven, ihlali ekleyen geliştirici, commit ve tarih.
Sırada ne var
- Hemen çalıştırmak için: 02 — Başlarken.
- İç yapıyı anlamak için: 03 — Mimari.
- Ayarlamak için: 11 — Özelleştirme kılavuzu.