feat(metrics): KL- & Jensen-Shannon-Divergenz (File-Verteilung vs. Codebase)

[aspala]

Was & Warum

CombinedMetrics.CosineVector misst File-Ähnlichkeit über Vektoren, aber es gibt kein verteilungsbasiertes Outlier-Maß: wie untypisch ist die Token-Verteilung dieses Files gegenüber der gesamten Codebase?

• KL-Divergenz D(File ‖ Codebase) — gerichtet, kann unendlich werden bei fehlenden Tokens.
• Jensen-Shannon-Distanz — symmetrisch, beschränkt auf 0..1, immer endlich. Robuster, sollte das primäre Signal sein.

Das findet Fremdkörper: eine NIF-Bridge in einer reinen Phoenix-App, ein Migration-File neben GenServern.

Skala (JS-Distanz)

Verhalten	Beispiel	erwarteter Wert
niedrig (typisch)	CRUD-Context wie alle anderen	~0.1
mittel	LiveView in API-lastiger Codebase	~0.4
hoch (Fremdkörper)	handgeschriebene NIF-Bridge / Migration vs. GenServer	~0.8

Umsetzung

• Codebase-Metric, nicht File-Metric: braucht alle Files für das Korpus-Profil. Neues Modul lib/codeqa/metrics/codebase/distribution_divergence.ex, @behaviour CodeQA.Metrics.Codebase.CodebaseMetric (Muster wie Codebase.Similarity).
• Schritt 1: aggregiertes Korpus-Unigram-Profil über alle token_counts. Schritt 2: pro File KL + JS gegen das Profil. Laplace-Smoothing gegen Null-Wahrscheinlichkeiten.
• Output je File: %{"kl_divergence" => …, "js_distance" => …}; zusätzlich Codebase-Ebene: Top-N-Outlier-Liste.
• Registrieren in lib/codeqa/engine/analyzer.ex via Registry.register_codebase_metric/2.

Test

• test/codeqa/metrics/codebase/distribution_divergence_test.exs.
• Assertion: 5 homogene Files + 1 stark abweichendes → das abweichende hat höchste js_distance; identische Files → js_distance ≈ 0.0.