Geliştirme kılavuzu

CleanLens nasıl derlenir, test edilir, hata ayıklanır ve yayınlanır; ve nasıl genişletilir.

#Kurulum

git clone https://github.com/MUSAALAHMED4/CleanLens.git
cd CleanLens
npm install

Node.js ≥ 20 ve Git gerektirir.

#Betikler

vscode:prepublish / prepublishOnly, paketleme veya yayınlama öncesinde küçültülmüş paketleri otomatik derler.

#Proje yapısı

CleanLens/
├── src/                 source (see 03 — Architecture for the module map)
├── test/                node:test suites (run with tsx, no build needed)
├── dist/                build output (git-ignored)
├── docs/                this documentation + RULES.md + PRIVACY.md
├── media/               icons and screenshots
├── website/             marketing site (separate Next.js app; see 16)
├── .github/workflows/   CI
├── .vscode/             launch + build task for F5 debugging
├── package.json         manifest: extension contributions, bin, scripts
├── tsconfig.json        strict, ES2022, Node16 modules
├── .eslintrc.json       eslint:recommended + @typescript-eslint/recommended
├── README.md / README.ar.md   product page (EN / AR)
├── CHANGELOG.md         release notes
└── Clean_Code_Tracker_Plan.md  original design plan

• src/ kaynak kod (modül haritası için bkz. 03 — Mimari).
• test/ node:test test paketleri (tsx ile çalışır, derleme gerekmez).
• dist/ derleme çıktısı (git tarafından yok sayılır).
• docs/ bu dokümantasyon, RULES.md ve PRIVACY.md; çevirileri docs/ar/ ve docs/tr/ içindedir.
• website/ tanıtım sitesi (ayrı bir Next.js uygulaması; bkz. 16).

#Hata ayıklama

• Eklenti: F5 tuşuna basın. Run Extension yapılandırması npm: build görevini çalıştırır, ardından bu eklenti yüklü bir Extension Development Host açar. O pencerede herhangi bir Git deposunu açın ve komutları çalıştırın.
• CLI: npm run build:cli && node dist/cli.js /path/to/repo veya derlemeden npx tsx src/cli/index.ts /path/to/repo.
• Pano HTML'i: renderDashboardDocument(report, { nonce: "x", standalone: true }) tarayıcıda açabileceğiniz bir sayfa döndürür.

#Testler

Testler Node'un yerleşik node:test çalıştırıcısını ve tsx kullanır. VS Code örneği gerekmez: test edilen kod vscode içe aktarmaz.

Entegrasyon testleri geçici bir dizinde git init ile depolar oluşturur ve yalıtılmış, boş bir git yapılandırması kullanır; bu yüzden genel Git ayarlarınıza bağlı değildir. Tek bir dosyayı çalıştırmak için:

node --import tsx --test test/scoring.test.ts

#Sürekli entegrasyon

.github/workflows/ci.yml, main dalına yapılan push'larda ve pull request'lerde, Ubuntu, Windows ve macOS × Node 22 ve 24 üzerinde çalışır:

npm ci → typecheck → lint → test → build → vsce package.

Ubuntu / Node 24 işi .vsix dosyasını bir artifact olarak yükler. Windows bilerek dahil edilmiştir: yol ayıraçları, CRLF çıktısı ve git.exe çözümlemesi daha önce gerçek hatalara yol açtı (değişiklik günlüğüne bakın).

#Sürüm yayınlama

1. package.json içindeki version değerini artırın; CHANGELOG.md dosyasına bir girdi ekleyin.
2. CI'ın yeşil olduğundan emin olun.
3. npm run build && npx vsce package --no-dependencies → cleanlens-<version>.vsix.
4. npx vsce publish ile yayınlayın (cleanlens yayıncısı için bir PAT gerekir) veya .vsix dosyasını Marketplace yayıncı portalına yükleyin.
5. İsteğe bağlı olarak CLI için npm publish (aynı sürüm).
6. website/lib/constants.ts içindeki EXTENSION_VERSION değerini güncelleyin.

package.json içindeki files listesi neyin paketleneceğini belirler (hem .vsix hem de npm paketinde): iki paket, simgeler, README.md, CHANGELOG.md, docs/PRIVACY.md, docs/RULES.md, LICENSE.txt. Bu klasördeki diğer dokümanlar paketlenmez; pakette olmalarını istiyorsanız files listesine ekleyin.

#Kodlama kuralları

• TypeScript strict. Kaçınılmaz olmadıkça any yok.
• Yalnızca src/extension.ts ve src/views/* vscode içe aktarabilir.
• Analizörler saf fonksiyonlardır: (relPath, text, config) => RawFinding[].
• Her Git çağrısı execFile kullanır (kabuk yok) ve başarısızlığı açıkça ele alır.
• Ayarlanabilir sayılar src/scoring/scoringConfig.ts (puanlama) içinde veya modüllerinin başında adlandırılmış sabitler olarak yer alır.
• Bir değişiklik commit başına analiz sonuçlarını değiştiriyorsa ENGINE_VERSION değerini artırın.

#Kural ekleme

Örnek: yeni bir maxLineLength kuralı.

1. src/configuration/types.ts içinde kaydedin:
   • RULE_IDS listesine "maxLineLength" ekleyin;
   • RULE_TITLES içine bir başlık ekleyin (örn. "Long line");
   • RULE_CATEGORY içine kategorisini ekleyin (örn. "structure"). Ardından TypeScript yeni kimliğe ihtiyaç duyan her yeri gösterir.
2. src/configuration/presets.ts içindeki BASE_RULES'ta varsayılanlarını verin: maxLineLength: { enabled: true, severity: "low", limit: 120 }.
3. jsAnalyzer.ts ve/veya pyAnalyzer.ts içinde uygulayın:

   if (on("maxLineLength")) {
     const max = lim("maxLineLength", 120);
     text.split("\n").forEach((line, i) => {
       if (line.length > max) add("maxLineLength", i + 1, `Line has ${line.length} characters (limit ${max}).`);
     });
   }

   Bulgu bir fonksiyona veya sınıfa aitse symbolName geçirin; atamayı daha doğru yapar.
4. scoringConfig.ts içindeki ENGINE_VERSION değerini artırın.
5. test/jsAnalyzer.test.ts içinde test edin (olumlu ve olumsuz durumlar).
6. docs/RULES.md, 06 — Kural başvurusu (üç dilde) ve README kural tablolarında (İngilizce ve Arapça) belgeleyin.

Mevcut yapılandırma dosyaları yeni kuralı listelemez; bu yüzden kullanıcılar ekleyene kadar onlar için kapalıdır (bulunmayan kural kapalıdır). Doğrulayıcı, kural RULE_IDS içine eklendiği anda onu kabul eder.

#Dil ekleme

1. analyze<Lang>(filePath, text, config): RawFinding[] fonksiyonunu ve uzantı listesini dışa aktaran src/analyzers/<lang>Analyzer.ts dosyasını oluşturun. model.ts içindeki ruleEnabled, ruleLimit, ruleOption fonksiyonlarını kullanın ve secrets.ts / names.ts dosyalarını yeniden kullanın.
2. runAnalyzers.ts içinde kaydedin: uzantıları ALL_EXTENSIONS listesine ve analyzerFor() içine bir dal ekleyin. HEAD taraması, commit yürüyüşü ve canlı tanıların tümü analyzerFor() kullanır; başka bir şeyi bağlamaya gerek yoktur.
3. fingerprint.ts dosyasının o dilin satır yorumu sözdizimini temizlediğini kontrol edin (bugün // ve #).
4. presets.ts içinde bir ön ayar ve detectPreset() içinde tespitini düşünün.
5. ENGINE_VERSION değerini artırın, testler ekleyin, dokümanları güncelleyin.

#Dokümantasyon ve çeviriler

Dokümanlar aynı dosya adlarıyla üç dilde bulunur:

docs/*.md      English — the source of truth
docs/ar/*.md   Arabic
docs/tr/*.md   Turkish

İngilizce asıl kaynaktır. Bir İngilizce dokümanı değiştirdiğinizde iki çeviriyi aynı değişiklikte güncelleyin. Web sitesindeki doküman sayfalarının (bkz. 16) çalışmaya devam etmesini sağlayan kurallar:

• Başlık yapısını aynı tutun (aynı sayıda başlık, aynı düzeyler, aynı sıra). Site, çevrilmiş başlıklara konumlarına göre İngilizce bağlantı kimliklerini verir; böylece bağlantılar ve URL'ler her dilde aynıdır.
• Bölüm bağlantıları her dilde İngilizce kimlikleri kullanır (örn. 08-scoring.md#severity-weights).
• docs/ dışındaki dosyalara giden bağlantılar çevirilerde bir düzey daha yukarı çıkar (../src/… yerine ../../src/…).
• Kod blokları, tanımlayıcılar, kural kimlikleri, yapılandırma anahtarları ve CLI çıktısı İngilizce kalır.
• Bir çeviri dosyası yoksa site İngilizce olanı gösterir.

#VS Code ayarı ekleme

1. package.json içinde contributes.configuration.properties altında tanımlayın.
2. src/extension.ts içindeki readSettings() fonksiyonunda okuyun.
3. Bir yapılandırma anahtarına karşılık geliyorsa src/core/analyzeRepository.ts içindeki ExtensionSettings ve applySettings() yapılarına ekleyin. Kullanıcı ayarlamadıysa undefined tercih edin; böylece yapılandırma dosyası bir varsayılan tarafından geçersiz kılınmaz.
4. 10 — Yapılandırma başvurusu içinde belgeleyin.