Özelleştirme kılavuzu

Bu kılavuz CleanLens'i ekibinizin ihtiyaçlarına göre nasıl ayarlayacağınızı anlatır: neyi, nerede değiştireceğinizi ve bunun etkisini. Anahtarların ve tiplerinin tam listesi için bkz. 10 — Yapılandırma başvurusu.

İçindekiler

1. Bir başlangıç noktası seçin
2. Kurallar: katılık ve gürültü
3. Neyin analiz edileceği: hariç tutmalar
4. Puanlama
5. Geliştirici kimlikleri
6. Geçmiş penceresi
7. Editör deneyimi
8. CI kalite kapıları
9. Kişisel geçersiz kılmalar
10. Hazır ekip profilleri
11. Kendi deponuzda kalibrasyon
12. Kaynak kodda özelleştirme
13. VS Code ve CLI'ı uyumlu tutun

#1. Bir başlangıç noktası seçin

CleanLens: Initialize Project komutunu çalıştırın ve depoya uyan ön ayarı seçin:

Ardından oluşturulan .clean-code-tracker.json dosyasını düzenleyin. Ön ayar yalnızca dosyayı oluşturmak için kullanılır; sonraki değişiklikler size aittir.

#2. Kurallar: katılık ve gürültü

#Kural başına üç kaldıraç

Pratik kural: Bir kural sağlam saydığınız kodda tetikleniyorsa limit değerini değiştirin; doğru tetikleniyor ama sizin için daha az (veya daha çok) önemliyse severity değerini değiştirin; kod tabanınız için çoğunlukla yanlışsa kapatın.

#Katılık profilleri

requireSingleResponsibility kuralının 1.5 × maxFunctionLines.limit ve 1.5 × maxComplexity.limit değerlerini aşan fonksiyonlarda da tetiklendiğini unutmayın; bu iki sınırı değiştirmek onu da etkiler.

#Gürültüyü azaltmak

Gürültünün çoğu birkaç sezgisel kuraldan gelir. Bunları sırayla deneyin:

1. requireErrorHandling: hatalar merkezi olarak yönetiliyorsa (Express hata middleware'i, Django view'ları, bir React Query katmanı), low seviyesine düşürün veya kapatın.

   "requireErrorHandling": { "enabled": true, "severity": "low" }

2. forbidDebugStatements: print / console.log'un asıl çıktı olduğu CLI araçları ve betikler için, kuralı tüm projede kapatmak yerine o klasörleri hariç tutun (3. bölüm).
3. requireDocumentationForComplexCode: complexityThreshold değerini 20+ yapın veya ekibiniz normal yorumlarla belgeliyorsa kapatın.
4. requireSingleResponsibility: büyük ama tutarlı sınıfları olan çatılar için (Django admin, sınıf bileşenleri, servis nesneleri) maxMethods değerini yükseltin.
5. Python maxNestingDepth: Python derinliği class ve def düzeylerini sayar; bu yüzden bir metot gövdesi zaten 2. derinlikten başlar. Python ağırlıklı depolar için limit: 5 veya 6 kullanın.

#Sizin için önemli olanı vurgulamak

• Önce güvenlik: forbidHardcodedSecrets kuralını critical tutun ve forbidEmptyCatchBlocks kuralını critical seviyesine çıkarın.
• Önce bakım kolaylığı: maxComplexity ve maxNestingDepth kurallarını critical seviyesine çıkarın, isimlendirme ve hata ayıklama kurallarını low seviyesine düşürün.
• Eski bir kod tabanına başlamak: başta yapı kuralları için sınırları gevşek ve önem derecelerini düşük tutun; birkaç sprint'te bir sıkılaştırın.

#3. Neyin analiz edileceği: hariç tutmalar

Ekibinizin yazmadığı ve bakımını yapmadığı her şeyi hariç tutun. Bu, analizi daha hızlı ve daha adil yapar.

#Kalıplar nereye eklenir

#Yaygın kalıplar

"exclude": [
  "**/__tests__/**", "*.test.*", "*.spec.*",   // testler
  "**/fixtures/**", "**/__mocks__/**",          // test verileri
  "scripts/**", "tools/**",                     // tek seferlik betikler
  "**/third_party/**", "public/vendor/**",      // dışarıdan alınmış kod
  "**/*.d.ts",                                  // tip bildirimleri
  "docs/**/*.js"                                // dokümanlardaki örnekler
]

(Yorumlar yalnızca açıklama içindir; gerçek dosya düz JSON olmalıdır.)

Kalıp ipuçları:

• folder/** o klasörle her derinlikte eşleşir. Yalnızca kökte eşleşmek için /folder/** kullanın.
• / içermeyen *.ext dosya adıyla her yerde eşleşir.
• Olumsuzlama (!), {a,b}, [abc] yok. Bunun yerine ayrı kalıplar yazın.

#Üretilmiş dosyalar

excludeGenerated: true (varsayılan) olarak bırakın. Üretilmiş dosyaları açıkça işaretlemek için:

# .gitattributes
src/api/client.ts linguist-generated
proto/*.ts        linguist-generated

Veya dosyanın ilk beş satırına // @generated / # DO NOT EDIT yazın.

#Testler analiz edilmeli mi?

• Puanların yalnızca üretim kodunu yansıtmasını istiyorsanız hariç tutun (react / python ön ayarları bunu yapar).
• Test kalitesi sizin için önemliyse dahil edin. detectDuplicateCode kuralını low seviyesine düşürmeyi düşünün: testler doğası gereği çoğu zaman tekrarlıdır.

#Migration'lar

excludeMigrations: true (varsayılan) **/migrations/** yolunu atlar. Bunu yalnızca migration'larınız elle yazılıyor ve uygulama kodu gibi inceleniyorsa false yapın.

#4. Puanlama

Puanlar, 100 × e^(−density / scale) ile eşlenen 1.000 satır başına ağırlıklı puanlardan gelir. Tam formül için bkz. 08 — Puanlama.

#Kaldıraç 1 — kural önem derecesi (ana ağırlık kontrolü)

Bir ihlalin ağırlığı, kuralının severity değerinden gelir: low 1, medium 3, high 5, critical 8. Bir kuralın daha çok veya daha az sayılmasını sağlamanın yolu budur.

#Kaldıraç 2 — kategori ölçekleri (genel hoşgörü)

scoring.categoryScales, bir kategorinin ne kadar yoğunluğa tolerans göstereceğini belirler. Büyük ölçek = daha hoşgörülü.

"scoring": { "categoryScales": { "structure": 60 } }

Ölçeği bir hedeften seçin: "yoğunluğu d olan bir geliştirici s alt puanı almalı":

scale = d / −ln(s / 100)

Örnek: en iyi geliştiricilerinizin yapı yoğunluğu yaklaşık 12. Yapıda 80 almalarını istiyorsunuz → scale = 4.5 × 12 = 54.

#Kaldıraç 3 — kategori ağırlıkları (en önemli olan)

scoring.weights, her alt puanın nihai puandaki payını belirler. Toplamı 1 tutun.

Ağırlıkların toplamı 1 değilse puanlar büyütülür veya küçültülür (ve 0–100'e sıkıştırılır); bu da karşılaştırmayı zorlaştırır. Bundan kaçının.

#Kaldıraç 4 — sıralama eşiği

scoring.minLinesForRanking (varsayılan 1000):

• Küçük ekip / kısa pencere: insanların sıralamaya girebilmesi için 300–500'e düşürün.
• Büyük ekip / resmi değerlendirme: yalnızca iyi desteklenen puanların karşılaştırılması için 2.000–5.000'e çıkarın.

VS Code'da cleanlens.scoring.minLinesForRanking ayarını kullanın: bu ayar yapılandırma dosyasını geçersiz kılar (bkz. 13. bölüm).

#Yapılandırılamayanlar (yalnızca kaynak kodda)

Büzülme gücü (PRIOR_KLOC = 1), güven seviyesi eşikleri (300 / 1.000 / 5.000 satır) ve hangi atama güvenlerinin puana girdiği (high + medium). Bkz. 12. bölüm.

#5. Geliştirici kimlikleri

İnsanlar çoğu zaman birkaç e-postayla veya adlarını farklı yazarak commit atar. CleanLens bunları en açıktan en örtüğe üç yolla birleştirir:

#a) Yapılandırmada açık liste (ekipler için önerilir)

"developers": [
  { "displayName": "Musa Alahmed", "emails": ["musa@company.com", "12345+musa@users.noreply.github.com"] },
  { "displayName": "Ayman Khalil", "emails": ["ayman@company.com", "ayman.k@gmail.com"] }
]

• Listelenen tüm e-postalar displayName ile gösterilen tek bir geliştirici olur.
• E-posta eşleştirmesi büyük/küçük harfe duyarsızdır.

#b) .mailmap (Git düzeyinde; git log / git shortlog çıktısını da düzeltir)

Musa Alahmed <musa@company.com> <musa.personal@gmail.com>
Musa Alahmed <musa@company.com> MUSAALAHMED4 <12345+MUSAALAHMED4@users.noreply.github.com>

#c) Otomatik birleştirme (mergeSameNameAuthors, varsayılan açık)

Aynı ada, boşluklar, noktalama ve sondaki rakamlar yok sayıldığında aynı olan ada veya aynı ayırt edici e-posta tanıtıcısına sahip kimlikleri birleştirir. Ayrıntılar: 04 — Git katmanı.

Aynı adı taşıyan iki farklı kişi varsa kapatın, ardından gerçek birleştirmeleri açıkça listeleyin:

"mergeSameNameAuthors": false

(VS Code'da da cleanlens.mergeSameNameAuthors değerini false yapın; ayar kazanır.)

#Botlar

Botlar (Dependabot, Renovate, CI) geliştirici olarak görünür. Genellikle yalnızca kilit ve yapılandırma dosyalarına dokunurlar; bu yüzden 0 analiz edilen satırları ve sıralanmayan bir "no analysed code" puanları olur. Onları gizleme seçeneği yoktur. Raporda yok sayabilir veya developers listesiyle tek bir ad altında gruplayabilirsiniz.

#6. Geçmiş penceresi

Yalnızca pencere içinde eklenen ihlaller atanır. Daha eskiler existing olarak görünür ve kimseye yazılmaz.

İkisi birden ayarlandığında Git ikisini de uygular: since sonrasındaki commit'ler, ardından bunların en yeni maxCommits tanesi.

Pencere genişledikçe her geliştiricinin kodu artar, puan güveni yükselir ve existing ihlaller azalır. Önbellek açıkken yalnızca ilk geniş çalıştırma yavaştır.

#7. Editör deneyimi

• Canlı tanılar (cleanlens.liveDiagnostics, varsayılan açık): dosya düzeyindeki kuralları kullanarak siz yazarken sorunların altını çizer. Dikkat dağıtıyorsa veya büyük dosyalarda yavaşsa kapatın; tam analiz tanıları kalır.
• Tanı düzeyi önem derecesini izler: critical/high → Error (kırmızı), medium → Warning (sarı), low → Information (mavi). Bir kuralı editörde daha sessiz yapmak için önem derecesini düşürün (bu, puandaki ağırlığını da düşürür).
• Canlı tanılar hariç tutma listesini uygulamaz: açtığınız hariç tutulmuş bir dosyada da canlı altı çizili uyarılar görünür. Tam analiz sonuçları etkilenmez.

#8. CI kalite kapıları

CLI'ın çıkış kodlarını kullanın (0 = başarılı, 1 = kapı başarısız, 2 = hata):

# Mevcut kodda herhangi bir high veya critical ihlalde başarısız ol
cleanlens --fail-on high

# Kişisel geçersiz kılmaları yok sayan ve bilinen bir kural seti kullanan tekrarlanabilir kapı
cleanlens --preset django --fail-on critical --no-cache

# Raporu bir CI artifact'ı olarak yayınla
cleanlens --markdown > cleanlens-report.md
cleanlens --json > cleanlens-report.json

Bilinmesi gerekenler:

• --fail-on, existing olanlar dahil mevcut koddaki tüm ihlalleri denetler. Eski bir kod tabanında --fail-on critical ile başlayın (örneğin yalnızca gizli bilgiler) ve zamanla sıkılaştırın.
• CI'da yerel geçersiz kılma dosyası yoktur (git tarafından yok sayılır); bu yüzden CI ekip yapılandırmasını kullanır. İstediğiniz de budur.
• CI'ı hızlı tutmak için --max-commits kullanın; atama --fail-on sonucunu etkilemez.

Tam örnekler (GitHub Actions, pre-commit kancası): 13 — CLI.

#9. Kişisel geçersiz kılmalar

Ekibinizi etkilemeden denemek için .clean-code-tracker.local.json oluşturun:

{
  "rules": { "maxFunctionLines": { "limit": 60 } },
  "exclude": ["sandbox/**"]
}

Yalnızca rules (kural başına birleştirilir) ve exclude (eklenir) okunur. Dosya doğrulanmaz; bu yüzden kural kimliklerini dikkatle kontrol edin. .gitignore içinde olduğundan emin olun.

#10. Hazır ekip profilleri

Birini kopyalayın, sonra ayarlayın. Yalnızca varsayılan ön ayardan farklar gösterilmiştir; bunları dosyanızın rules / scoring bölümlerine birleştirin.

#Girişim / hızlı ilerleyen ürün

Daha gevşek yapı sınırları, gerçek hatalara ve gizli bilgilere odak.

{
  "rules": {
    "maxFunctionLines": { "enabled": true, "severity": "low", "limit": 60 },
    "maxFileLines": { "enabled": true, "severity": "low", "limit": 600 },
    "maxComplexity": { "enabled": true, "severity": "medium", "limit": 12 },
    "requireDocumentationForComplexCode": { "enabled": false, "severity": "low" },
    "requireErrorHandling": { "enabled": true, "severity": "low" }
  },
  "scoring": { "categoryScales": { "structure": 60 } }
}

#Kurumsal / düzenlemeye tabi

Katı sınırlar, zorunlu belgeleme, sıralamadan önce daha fazla kanıt.

{
  "rules": {
    "maxFunctionLines": { "enabled": true, "severity": "medium", "limit": 30 },
    "maxComplexity": { "enabled": true, "severity": "high", "limit": 8 },
    "maxNestingDepth": { "enabled": true, "severity": "high", "limit": 3 },
    "forbidEmptyCatchBlocks": { "enabled": true, "severity": "critical" },
    "requireDocumentationForComplexCode": { "enabled": true, "severity": "medium", "options": { "complexityThreshold": 10 } }
  },
  "analysis": { "maxCommits": 0 },
  "scoring": { "minLinesForRanking": 3000 }
}

#Önce güvenlik

{
  "rules": {
    "forbidHardcodedSecrets": { "enabled": true, "severity": "critical" },
    "forbidEmptyCatchBlocks": { "enabled": true, "severity": "critical" },
    "requireErrorHandling": { "enabled": true, "severity": "high" },
    "forbidDebugStatements": { "enabled": true, "severity": "medium" }
  },
  "scoring": { "weights": { "duplication": 0.2, "structure": 0.35, "hygiene": 0.45 } }
}

#Eski kod tabanı (ilk aylar)

Yalnızca yeni işi yazın, eski borcu görünür ama puansız tutun, zamanla sıkılaştırın.

{
  "rules": {
    "maxFileLines": { "enabled": true, "severity": "low", "limit": 1000 },
    "maxFunctionLines": { "enabled": true, "severity": "low", "limit": 80 },
    "detectDuplicateCode": { "enabled": true, "severity": "low", "options": { "minLines": 10 } }
  },
  "analysis": { "since": "2026-09-01" }
}

since = ekibin temizliğe başladığı tarih: daha eski her şey existing olur.

#Python / Django arka ucu

{
  "rules": {
    "maxNestingDepth": { "enabled": true, "severity": "high", "limit": 5 },
    "requireSingleResponsibility": { "enabled": true, "severity": "medium", "options": { "maxMethods": 15 } },
    "maxFileLines": { "enabled": true, "severity": "medium", "limit": 500 }
  }
}

#11. Kendi deponuzda kalibrasyon

CleanLens'i bir ekibe uydurmanın tekrarlanabilir yolu:

1. Gerçek depoda geniş çalıştırın:

   cleanlens --full-history --markdown > baseline.md

2. "Severity breakdown" ve "Files with violations" bölümlerini okuyun. En çok bulgusu olan kuralları bulun.
3. Önce gürültüyü giderin. En gürültülü kuraldan 10 bulgu açın. Çoğu ekibiniz için gerçek sorun değilse o kuralın limit veya severity değerini değiştirin ya da kapatın (2. bölüm). Size ait olmayan kodu hariç tutun (3. bölüm).
4. Kimlikleri kontrol edin. Birileri ikiye mi bölünmüş? developers veya bir .mailmap ekleyin (5. bölüm).
5. Ancak ondan sonra puanlara bakın. Bir kategori herkes için düşükse, kural seti veya ölçek bağlamınız için fazla katıdır. O kategorinin ölçeğini ayarlamak için 4. bölümdeki formülü kullanın.
6. Yapılandırmayı dondurun ve commit'leyin. Kuralları her hafta değiştirmek puanları zaman içinde karşılaştırılamaz yapar (ve önbelleği temizler).
7. Ekibe anlatın. Kural setini ve sınırlamaları (17) ekiple paylaşın. Puanlar kodu iyileştirmek içindir, insanları sıralamak için değil.

#12. Kaynak kodda özelleştirme

Bazı davranışlar kodda sabittir. Değiştirin, yeniden derleyin (npm run build) ve değişiklik analiz sonuçlarını etkiliyorsa eski önbelleklerin atılması için src/scoring/scoringConfig.ts içindeki ENGINE_VERSION değerini artırın.

Yeni bir kural veya yeni bir dil eklemek 15 — Geliştirme kılavuzu içinde anlatılmıştır.

#13. VS Code ve CLI'ı uyumlu tutun

Eklentide şu VS Code ayarları, varsayılan değerlerinde bile yapılandırma dosyasını geçersiz kılar: excludeGenerated, excludeMigrations, excludeLockFiles, mergeSameNameAuthors, analysis.maxCommits, scoring.minLinesForRanking. (Ayrıntılar: 10 — Öncelik.)

Eklentiden, CLI'dan ve CI'dan aynı sayıları almak için:

1. Ekip yapılandırmasını .clean-code-tracker.json içine koyun.
2. Yukarıdaki ayarlar için aynı değerleri içeren bir .vscode/settings.json dosyası commit'leyin, örneğin:

   {
     "cleanlens.analysis.maxCommits": 0,
     "cleanlens.scoring.minLinesForRanking": 3000,
     "cleanlens.mergeSameNameAuthors": true
   }

3. Her yerde kullanmıyorsanız CI'da --preset kullanmayın.
4. Kişisel geçersiz kılmaları paylaşılan raporların dışında tutun.