Yapılandırma başvurusu

.clean-code-tracker.json içindeki her anahtar, yerel geçersiz kılma dosyası, VS Code ayarları, CLI bayrakları ve hangisinin geçerli olduğu

6 dk okuma7 bölüm

CleanLens dört yerde yapılandırılabilir:

Yer	Kapsam	Kim kullanır
`.clean-code-tracker.json`	Proje; ekiple paylaşmak için depoya commit'leyin	Eklenti + CLI
`.clean-code-tracker.local.json`	Kişisel; git tarafından yok sayılır	Eklenti + CLI (`--preset` ile değil)
VS Code ayarları (`cleanlens.*`)	Kullanıcı veya çalışma alanı	Yalnızca eklenti
CLI bayrakları	Tek çalıştırma	Yalnızca CLI

Bu doküman her seçeneği listeler. Hangi değerlerin seçileceği için bkz. 11 — Özelleştirme kılavuzu.

1. `.clean-code-tracker.json`

Depo kökünde bulunur. CleanLens: Initialize Project ile veya elle oluşturun. Yoksa javascript ön ayarı kullanılır ve bir uyarı gösterilir.

Tam örnek (her anahtar)

json

{
  "version": 1,
  "rules": {
    "maxFunctionLines":  { "enabled": true, "severity": "medium", "limit": 40 },
    "maxFileLines":      { "enabled": true, "severity": "medium", "limit": 400 },
    "maxParameters":     { "enabled": true, "severity": "medium", "limit": 5 },
    "maxComplexity":     { "enabled": true, "severity": "high",   "limit": 10 },
    "maxNestingDepth":   { "enabled": true, "severity": "high",   "limit": 4 },
    "detectDuplicateCode": { "enabled": true, "severity": "medium", "options": { "minLines": 6 } },
    "detectUnusedCode":  { "enabled": true, "severity": "low" },
    "requireClearVariableNames": { "enabled": true, "severity": "low" },
    "requireErrorHandling":      { "enabled": true, "severity": "medium" },
    "forbidEmptyCatchBlocks":    { "enabled": true, "severity": "high" },
    "forbidHardcodedSecrets":    { "enabled": true, "severity": "critical" },
    "forbidDebugStatements":     { "enabled": true, "severity": "low" },
    "requireSingleResponsibility": { "enabled": true, "severity": "medium", "options": { "maxMethods": 10 } },
    "requireDocumentationForComplexCode": { "enabled": true, "severity": "low", "options": { "complexityThreshold": 15 } }
  },
  "exclude": ["node_modules/**", "dist/**", "*.min.js", "scripts/**"],
  "excludeGenerated": true,
  "excludeMigrations": true,
  "excludeLockFiles": true,
  "mergeSameNameAuthors": true,
  "developers": [
    { "displayName": "Musa Alahmed", "emails": ["musa@work.com", "musa.personal@gmail.com"] }
  ],
  "analysis": {
    "maxCommits": 500,
    "since": "2026-01-01"
  },
  "scoring": {
    "categoryScales": { "duplication": 15, "structure": 45, "hygiene": 38 },
    "weights": { "duplication": 0.3, "structure": 0.45, "hygiene": 0.25 },
    "minLinesForRanking": 1000
  }
}

Anahtarlar

Anahtar	Tip	Varsayılan	Açıklama
`version`	`1`	— (zorunlu)	Şema sürümü. Tam olarak `1` olmalıdır.
`rules`	nesne	— (zorunlu)	Her kural kimliği için bir girdi. Bilinmeyen kimlikler hatadır. Bulunmayan bir kural kapalıdır. Bkz. 06.
`rules.<id>.enabled`	boolean	— (zorunlu)	Kuralı açar/kapatır.
`rules.<id>.severity`	`low`/`medium`/`high`/`critical`	— (zorunlu)	Ağırlık 1/3/5/8; ayrıca editördeki tanı düzeyi.
`rules.<id>.limit`	sayı > 0	kurala göre	Sayısal kurallar için eşik.
`rules.<id>.options`	`{ [k]: number \| boolean }`	kurala göre	`minLines`, `maxMethods`, `complexityThreshold`.
`exclude`	string[]	`[]`	Ek glob kalıpları. Yerleşik listeye eklenir, onun yerini asla almaz. Bkz. 05 — glob sözdizimi.
`excludeGenerated`	boolean	`true`	`linguist-generated` dosyalarını ve ilk 5 satırında "generated" / "do not edit" yazan dosyaları atla.
`excludeMigrations`	boolean	`true`	`/migrations/` hariç tut.
`excludeLockFiles`	boolean	`true`	`package-lock.json`, `yarn.lock`, `pnpm-lock.yaml` hariç tut.
`mergeSameNameAuthors`	boolean	`true`	Aynı kişiye benzeyen kimlikleri otomatik birleştir. Bkz. 04.
`developers`	`{ displayName, emails[] }[]`	`[]`	E-postaları sabit bir görünen adla tek bir geliştiriciye zorla.
`analysis.maxCommits`	sayı ≥ 0	`500`	Birleştirme olmayan en yeni N commit'i yeniden oynat. `0` = tüm geçmiş.
`analysis.since`	string	yok	Yalnızca bu tarihten sonraki commit'leri yeniden oynat. Herhangi bir `git log --since` değeri.
`scoring.categoryScales`	`{ duplication?, structure?, hygiene? }`	15 / 45 / 38	Bir alt puanın ~37'ye düştüğü yoğunluk. Büyük = daha hoşgörülü.
`scoring.weights`	`{ duplication?, structure?, hygiene? }`	0.30 / 0.45 / 0.25	Her alt puanın nihai puandaki payı. Toplamı 1 olmalıdır.
`scoring.minLinesForRanking`	sayı	`1000`	Sıralanmak için gereken analiz edilen satırlar.
`scoring.severityWeights`	`{ low?, medium?, high?, critical? }`	1 / 3 / 5 / 8	Kabul edilir, ancak şu anda puanları etkilemez (bkz. 08). Bunun yerine kuralın `severity` değerini kullanın.

scoring.* için kısmi nesneler sorun değildir: eksik anahtarlar varsayılanlarını korur.

Doğrulama

Dosya yüklenirken doğrulanır (configValidator.ts). Herhangi bir hata, tüm sorunların listesiyle analizi durdurur; örneğin:

text

.clean-code-tracker.json is invalid:
- Rule "maxComplexity": "severity" must be one of critical | high | medium | low.
- Unknown rule: "maxLineLength". Supported rules: maxFunctionLines, …

Denetlenenler: version === 1; rules, her biri boolean enabled, geçerli severity, varsa pozitif limit ve sayı/boolean options içeren bilinen kimliklerden oluşan bir nesnedir; exclude bir string dizisidir; dört bayrak boolean'dır; developers doğru biçimdedir; scoring ve analysis nesnedir; analysis.maxCommits negatif olmayan bir sayıdır; analysis.since bir string'dir.

Dosya katı JSON olmalıdır (yorum yok, sonda virgül yok).

2. `.clean-code-tracker.local.json`

Kişisel bir geçersiz kılma; bu deponun kendi .gitignore dosyasında yok sayılır (sizinkine de ekleyin). Yalnızca iki anahtar okunur:

Anahtar	Davranış
`rules`	Her girdi proje kuralıyla yüzeysel olarak birleştirilir: `{ ...project, ...local }`
`exclude`	Proje listesine eklenir

Örnek — iki kuralı kendiniz için susturmak ve bir deneme klasörünü atlamak:

json

{
  "rules": {
    "forbidDebugStatements": { "enabled": false },
    "maxComplexity": { "limit": 15 }
  },
  "exclude": ["playground/**"]
}

Notlar:

Yerel dosya doğrulanmaz. Bir kural kimliğindeki yazım hatası, hiçbir şeyin okumadığı bilinmeyen bir kural ekler. Yazımı iki kez kontrol edin.
Diğer anahtarlar (scoring, analysis, developers, …) yok sayılır.
Yerel geçersiz kılma yapılandırma hash'ini değiştirir; bu yüzden önbelleğinizi de geçersiz kılar.
Yerel geçersiz kılmalar sayılarınızı ekip arkadaşlarınızınkinden farklı yapar. Resmi raporlar için değil, denemeler için kullanın.

3. VS Code ayarları

Settings → Extensions → CleanLens üzerinden veya settings.json içinde (kullanıcı için ya da çalışma alanı için .vscode/settings.json) ayarlayın.

Ayar	Tip	Varsayılan	Karşılığı
`cleanlens.liveDiagnostics`	boolean	`true`	Açık dosyaları yazarken yeniden denetle
`cleanlens.exclude`	string[]	`[]`	`exclude` listesine eklenir
`cleanlens.excludeGenerated`	boolean	`true`	`excludeGenerated`
`cleanlens.excludeMigrations`	boolean	`true`	`excludeMigrations`
`cleanlens.excludeLockFiles`	boolean	`true`	`excludeLockFiles`
`cleanlens.mergeSameNameAuthors`	boolean	`true`	`mergeSameNameAuthors`
`cleanlens.analysis.maxCommits`	sayı	`500`	`analysis.maxCommits`
`cleanlens.analysis.since`	string	`""`	`analysis.since` (boş = ayarlanmamış)
`cleanlens.scoring.minLinesForRanking`	sayı	`1000`	`scoring.minLinesForRanking`
`cleanlens.cache.enabled`	boolean	`true`	Commit başına önbelleği kullan
`cleanCodeTracker.liveDiagnostics`	boolean	`true`	`cleanlens.liveDiagnostics` için eski ad; yalnızca açıkça ayarlanmışsa okunur

Çalışma alanı settings.json örneği:

json

{
  "cleanlens.analysis.maxCommits": 0,
  "cleanlens.exclude": ["scripts/**", "**/fixtures/**"],
  "cleanlens.scoring.minLinesForRanking": 500
}

4. CLI bayrakları

Bayrak	Etkisi
`[path]`	Analiz edilecek depo (varsayılan: geçerli dizin)
`--preset <name>`	İki yapılandırma dosyası yerine bir ön ayar (`javascript`/`react`/`python`/`django`) kullan
`--max-commits <n>`	`analysis.maxCommits` değerini geçersiz kılar
`--full-history`	`--max-commits 0` ile aynı
`--since <date>`	`analysis.since` değerini geçersiz kılar
`--no-cache`	Önbelleği kapat
`--json`, `--markdown`, `--violations`, `--fail-on <sev>`	Çıktı ve çıkış kodu; bkz. 13 — CLI

5. Öncelik — hangi değer geçerli olur

CLI'da

text

built-in defaults
  ◀ .clean-code-tracker.json         (or --preset, which replaces both files)
  ◀ .clean-code-tracker.local.json   (rules + exclude only; skipped with --preset)
  ◀ --max-commits / --full-history / --since

Yani: yerleşik varsayılanlar, sonra proje dosyası (veya iki dosyanın yerini alan --preset), sonra yerel dosya (yalnızca kurallar ve hariç tutmalar; --preset ile atlanır), sonra CLI bayrakları; sonuncusu kazanır.

VS Code eklentisinde

text

built-in defaults
  ◀ .clean-code-tracker.json
  ◀ .clean-code-tracker.local.json   (rules + exclude only)
  ◀ VS Code settings

Önemli: eklentide aşağıdaki VS Code ayarları, siz değiştirmemiş olsanız bile, yapılandırma dosyasına karşı her zaman kazanır; çünkü ayarın varsayılan değeri bir değer olarak kullanılır:

excludeGenerated, excludeMigrations, excludeLockFiles, mergeSameNameAuthors, analysis.maxCommits, scoring.minLinesForRanking.

Örneğin yapılandırma dosyasındaki "analysis": { "maxCommits": 0 } CLI tarafından dikkate alınır ama eklenti tarafından yok sayılır; eklenti cleanlens.analysis.maxCommits (varsayılan 500) kullanır. İkisinde de aynı sonucu almak için değeri iki yerde de ayarlayın veya yapılandırmanın yanına commit'lenmiş bir çalışma alanı .vscode/settings.json dosyası kullanın.

exclude her yerde eklemelidir. VS Code'daki analysis.since yalnızca boş değilse uygulanır. scoring.categoryScales ve scoring.weights yalnızca yapılandırma dosyasından gelir.

Hızlı tablo

Seçenek	Yapılandırma dosyası	Yerel dosya	VS Code ayarı	CLI bayrağı
rules	✅	✅ (birleştirilir)	—	`--preset` yerini alır
exclude	✅	✅ (eklenir)	✅ (eklenir)	—
excludeGenerated / Migrations / LockFiles	✅ (CLI)	—	✅ (kazanır)	—
mergeSameNameAuthors	✅ (CLI)	—	✅ (kazanır)	—
developers	✅	—	—	—
analysis.maxCommits	✅ (CLI)	—	✅ (kazanır)	✅ (kazanır)
analysis.since	✅	—	✅ boş değilse	✅ (kazanır)
scoring.categoryScales / weights	✅	—	—	—
scoring.minLinesForRanking	✅ (CLI)	—	✅ (kazanır)	—
önbellek	—	—	✅	`--no-cache`
canlı tanılar	—	—	✅	—

6. CleanLens'in okuduğu diğer dosyalar

Dosya	Kullanım amacı
`.gitignore` (yalnızca kök)	Hariç tutma listesine eklenir (elden gelen en iyi şekilde, olumsuzlama yok)
`.gitattributes` (yalnızca kök)	`linguist-generated` yolları hariç tutulur
`.mailmap`	Git'in kendisi tarafından yazar adlarına/e-postalarına uygulanır
`manage.py`, `pyproject.toml`, `requirements.txt`, `setup.py`, `package.json`	Initialize Project içinde ön ayar önerisi

7. Ön ayarlar

Ön ayar	Kurallar	Ek hariç tutmalar (temel listenin üzerine)
`javascript`	temel kurallar	—
`react`	temel kurallar	`.stories.`, `storybook-static/`, `/__tests__/*`, `.test.`, `.spec.*`
`python`	temel kurallar	`__pycache__/*`, `.pyc`, `.mypy_cache/`, `.pytest_cache/`, `/tests/`, `test_*.py`, `conftest.py`
`django`	temel kurallar, `maxFileLines.limit` = 500	Python listesi + `/migrations/`, `manage.py`

Her ön ayardaki temel hariç tutma listesi: node_modules/**, .venv/**, venv/**, migrations/**, dist/**, build/**, coverage/**, staticfiles/**, *.min.js, *.generated.*.

#1. .clean-code-tracker.json

#Tam örnek (her anahtar)

#Anahtarlar

#Doğrulama

#2. .clean-code-tracker.local.json

#3. VS Code ayarları

#4. CLI bayrakları

#5. Öncelik — hangi değer geçerli olur

#CLI'da

#VS Code eklentisinde

#Hızlı tablo

#6. CleanLens'in okuduğu diğer dosyalar

#7. Ön ayarlar

1. `.clean-code-tracker.json`

Tam örnek (her anahtar)

Anahtarlar

Doğrulama

2. `.clean-code-tracker.local.json`

3. VS Code ayarları

4. CLI bayrakları

5. Öncelik — hangi değer geçerli olur

CLI'da

VS Code eklentisinde

Hızlı tablo

6. CleanLens'in okuduğu diğer dosyalar

7. Ön ayarlar