Mimari

Katmanlar, modül haritası, 7 adımlı işlem hattı, modüller arası veri akışı

4 dk okuma6 bölüm

Katmanlar

CleanLens, tek bir motoru ve iki ince arayüzü olan bir TypeScript projesidir.

text

┌──────────────────────────────┐   ┌──────────────────────────────┐
│  VS Code extension           │   │  CLI                         │
│  src/extension.ts            │   │  src/cli/index.ts            │
│  src/views/*                 │   │  src/cli/format.ts           │
└──────────────┬───────────────┘   └──────────────┬───────────────┘
               │   analyzeRepository(root, opts)  │
               └───────────────┬──────────────────┘
                               ▼
┌────────────────────────────────────────────────────────────────┐
│  Core pipeline — src/core/analyzeRepository.ts (no VS Code API) │
├──────────────┬──────────────┬───────────────┬──────────────────┤
│ git/         │ configuration│ analyzers/    │ attribution/     │
│ git commands │ config, rules│ rule checks   │ commit replay    │
│ + identities │ presets,     │ per file      │ + fingerprints   │
│              │ excludes     │               │                  │
├──────────────┴──────────────┴───────────────┼──────────────────┤
│ cache/ — per-commit results on disk         │ scoring/ — score │
└─────────────────────────────────────────────┴──────────────────┘

Yalnızca src/extension.ts ve src/views/* vscode içe aktarır. Geri kalan her şey düz Node.js'tir; CLI ve testlerin onu çalıştırabilmesinin nedeni budur.
typescript dışında çalışma zamanı bağımlılığı yoktur (JS analizörü tarafından ayrıştırıcı olarak kullanılır, esbuild ile pakete dahil edilir). Tüm Git erişimi execFile("git", …) üzerinden yapılır.

Modül haritası

Klasör	Dosya	Sorumluluk
`src/`	`extension.ts`	Etkinleştirme, komut kaydı, ilerleme arayüzü, VS Code ayarlarının okunması, canlı tanıların bağlanması
`src/core/`	`analyzeRepository.ts`	Ortak işlem hattı; ayarları yapılandırmanın üzerine birleştirir; önbelleği kurar; `ProjectReport` döndürür
`src/cli/`	`index.ts`	Argüman ayrıştırma, çıkış kodları, stdout/stderr yönetimi
	`format.ts`	Rapor → metin / Markdown; `--fail-on` denetimi
`src/git/`	`gitService.ts`	"Bu bir depo mu?", "Commit'i var mı?", katkıcı istatistikleri için `git log`
	`contributors.ts`	Commit'leri geliştiricilere gruplar; yinelenen kimlikleri birleştirir
	`commitHistory.ts`	Birleştirme olmayan commit'leri listeler (en yeni N / bir tarihten beri), en eskiden başlayarak
	`diffService.ts`	Commit başına bir `git diff` → değişen dosyalar, satır aralıkları, blob kimlikleri; blob okumak için `git cat-file --batch`
	`blameService.ts`	`git blame --line-porcelain` ayrıştırıcısı. Eski (önceki blame motorundan); hâlâ test ediliyor, işlem hattında kullanılmıyor
`src/configuration/`	`types.ts`	Yapılandırma tipleri, 14 kural kimliği, başlıkları ve kategorileri, dosya adları
	`configValidator.ts`	`.clean-code-tracker.json` şema doğrulaması
	`configLoader.ts`	Yapılandırmayı (veya varsayılan ön ayarı) yükler, yerel geçersiz kılmayı birleştirir, yeni yapılandırma yazar
	`presets.ts`	Dört ön ayar; ön ayarın otomatik tespiti
	`excludes.ts`	Yerleşik hariç tutmalar; `.gitignore` / `.gitattributes` okuma; üretilmiş dosya başlığı tespiti
`src/analyzers/`	`fileScanner.ts`	HEAD taraması için dizin gezintisi
	`glob.ts`	Minimal glob → RegExp ve `ExcludeMatcher`
	`jsAnalyzer.ts`	JS/TS için AST tabanlı kurallar (TypeScript derleyici API'si)
	`pyAnalyzer.ts`	Python için satır/girinti tabanlı kurallar
	`duplicateCode.ts`	Kayan pencere ile yinelenen blok tespiti
	`secrets.ts`, `names.ts`	Gizli bilgiler ve belirsiz isimler için ortak sezgiler
	`model.ts`	`RawFinding` → `Violation`; kuralın etkinlik/sınır/seçenek yardımcıları
	`runAnalyzers.ts`	HEAD taramasını yönetir; uzantıya göre analizörü seçer
	`analyzeRevision.ts`	Bir dosyanın tek bir sürümünü (blob) analiz eder ve her ihlale parmak izi verir
`src/attribution/`	`commitAttribution.ts`	Commit'leri gezer, önce/sonra karşılaştırır, her ihlali sınıflandırır
	`attributeReport.ts`	HEAD ihlallerini commit sonuçlarıyla birleştirir; geliştiricileri puanlar
	`fingerprint.ts`	FNV-1a hash; sabit ihlal parmak izi
	`ownership.ts`	E-posta → geliştirici kimliği eşlemesi (+ eski blame yardımcıları)
`src/scoring/`	`scoringConfig.ts`	Ayarlanabilir tüm sabitler: ağırlıklar, ölçekler, ön bilgi, eşikler, `ENGINE_VERSION`
	`cleanCodeScore.ts`	Puan formülü
`src/cache/`	`analysisCache.ts`	Commit başına JSON önbelleği + yapılandırma hash'i
`src/types/`	`index.ts`	`Severity`, `Violation`, `Developer`, `ProjectReport`, durumlar
`src/views/`	`treeProviders.ts`	Kenar çubuğu ağaçları + `ReportStore`
	`dashboardPanel.ts`	Webview panelinin yaşam döngüsü ve mesajları
	`dashboardHtml.ts`	Pano için saf HTML/CSS/JS üretimi
	`diagnostics.ts`	Editör tanıları: tam rapor beslemesi ve canlı besleme

İşlem hattı, adım adım

src/core/analyzeRepository.ts içindeki analyzeRepository(root, opts):

text

 1. Git checks        git rev-parse --is-inside-work-tree, git rev-parse HEAD
 2. Config            loadConfig()  →  applySettings(VS Code / CLI overrides)
                      readRepoAttributes() (.gitignore, .gitattributes)
                      mergedExcludeGlobs(), resolveScoring(), analysisConfigHash()
 3. Developers        git log --no-merges → aggregateContributors() → toDevelopers()
 4. HEAD scan         analyzeProject(): walk files → analyzer per file → duplicates
                      → sorted Violation[]
 5. Commit walk       attributeCommits(): newest N commits, oldest first,
                      12 in parallel, each: diff → blobs → analyze before/after
                      → introduced / fixed / existing
 6. Merge + score     attributeReport(): fingerprint every HEAD violation, look up
                      its origin, set status/confidence/developer; compute the
                      project prior; score every developer
 7. Display           extension: tree views, dashboard, diagnostics
                      CLI: text / Markdown / JSON + exit code

Aşamalar:

Git kontrolleri: Klasör bir depo mu? Commit'i var mı?
Yapılandırma: Yapılandırmayı yükle, VS Code ayarlarını veya CLI seçeneklerini üzerine birleştir, .gitignore ve .gitattributes dosyalarını oku, hariç tutma listesini, puanlama sabitlerini ve yapılandırma hash'ini oluştur.
Geliştiriciler: Git geçmişini oku ve commit'leri geliştiricilere grupla.
HEAD taraması: Mevcut dosyaları analiz et, sıralı ihlal listesini üret.
Commit yürüyüşü: En yeni N commit, en eskiden başlayarak, 12'si paralel; her biri için: diff → blob'lar → önce/sonra analizi → eklenen / düzeltilen / mevcut.
Birleştirme ve puanlama: HEAD'deki her ihlale parmak izi ver, kökenini bul, durumunu/güvenini/geliştiricisini belirle; proje ortalamasını hesapla ve her geliştiriciyi puanla.
Gösterim: Eklentide ağaç görünümleri, pano, tanılar; CLI'da metin / Markdown / JSON + çıkış kodu.

1–6. adımlar iki arayüz için de aynıdır. Yalnızca seçenekler farklıdır:

Seçenek	Eklenti	CLI
`config`	depodan yüklenir	depodan yüklenir veya `--preset`
`settings`	VS Code ayarlarından (`cleanlens.*`)	`--max-commits`, `--full-history`, `--since` bayraklarından
`cacheDir`	`context.globalStorageUri`	`<os tmpdir>/cleanlens-cache`
`cache`	`cleanlens.cache.enabled`	`--no-cache` ile kapalı
`signal`	ilerleme bildirimindeki Cancel düğmesi	yok

Beklenen hatalar

AnalysisError, kullanıcının düzeltebileceği sorunlarda fırlatılır: Git deposu değil, commit yok, geçersiz yapılandırma. Eklenti bunu hata mesajı olarak gösterir; CLI error: … yazdırır ve 2 koduyla çıkar. Bunun dışındaki her istisna bir hatadır (bug).

Veri akışı ve tipler

text

RawFinding  ──toViolation()──▶  Violation (severity, category, weight, id)
                                   │
       analyzeRevision()           │  fingerprintFor()
                                   ▼
RevisionViolation (+fingerprint) ─▶ CommitContribution (per commit, cached)
                                   │
                    attributeCommits() aggregates
                                   ▼
            DeveloperAttribution (per developer) + origins (fingerprint → commit)
                                   │
                        attributeReport()
                                   ▼
                  ProjectReport { developers[], violations[] }

Tip tanımları src/types/index.ts ve src/configuration/types.ts içindedir. Rapor biçimi 14 — Rapor şeması içinde alan alan belgelenmiştir.

İki analiz, iki amaç

Anlaşılması gereken en önemli tasarım noktası budur:

	HEAD taraması (4. adım)	Commit yürüyüşü (5. adım)
Girdi	şu anda diskte olan dosyalar	Git geçmişindeki blob'lar
Çıktı	size gösterilen ihlal listesi	kim neyi ekledi / düzeltti ve analiz edilen satırlar
Tekrar tespiti	tüm dosyalar arasında	yalnızca her dosyanın içinde
Kapsam	analiz edilebilir her dosya	yalnızca analiz edilen commit'lerin değiştirdiği dosyalar

Altıncı adım ikisini parmak izleriyle birleştirir. Parmak izi yürüyüş sırasında eklenmiş bir HEAD ihlali, o commit'in yazarına atanır. Yürüyüşte hiç görünmeyen bir HEAD ihlali, analiz penceresinden eskidir → existing.

Derleme çıktıları

esbuild iki bağımsız dosya paketler:

dist/extension.js — giriş noktası src/extension.ts, vscode paket dışında tutulur.
dist/cli.js — giriş noktası src/cli/index.ts, başında #!/usr/bin/env node satırı; cleanlens komutu olarak sunulur.

Derleme komutları için bkz. 15 — Geliştirme kılavuzu.

#Katmanlar

#Modül haritası

#İşlem hattı, adım adım

#Beklenen hatalar

#Veri akışı ve tipler

#İki analiz, iki amaç

#Derleme çıktıları

Katmanlar

Modül haritası

İşlem hattı, adım adım

Beklenen hatalar

Veri akışı ve tipler

İki analiz, iki amaç

Derleme çıktıları