feat(metrics): Rényi entropy spectrum & Hill numbers (#46)

[aspala]

Was & Warum

Schließt #46. Metrics.File.Entropy liefert nur Shannon (α=1). Rényi-Entropie verallgemeinert das über einen Order-Parameter α: kleine α gewichten seltene Tokens, große α nur die häufigsten. Ergebnis ist ein Spektrum statt eines Skalars — charakterisiert die Verteilungsform robuster.

Hill-Numbers D_α = 2^(H_α) sind die „effektive Vokabulargröße": wie viele Tokens wirklich zählen — interpretierbarer als rohe vocab_size.

Frequenzen kommen aus ctx.token_counts, also quasi gratis (gleicher Aufbau wie Shannon).

Umsetzung

Neues Modul lib/codeqa/metrics/file/renyi_entropy.ex, @behaviour FileMetric. 7 keys:

key	Definition
renyi_0	log2(vocab_size) — Hartley, zählt nur Support
renyi_1	-Σ pᵢ log2 pᵢ — Shannon-Limit (α→1)
renyi_2	-log2(Σ pᵢ²) — Collision
renyi_inf	-log2(max pᵢ) — Min-Entropie
hill_1 / hill_2	2^H_α — effektive Vokabulargröße
spectrum_slope	H₀ − H₂ — Konzentrations-Indikator (roh, wie spezifiziert)

• Registriert in analyzer.ex direkt nach LexicalConcentration — beide messen Konzentration (Rényi über Entropy-Achse, Yule/Simpson über Frequenz-Spektrum), komplementär (feat(metrics): Yule's K / Simpson's D (längen-invariante Vokabular-Konzentration) #44).
• Werte auf Float.round(_, 4) — konsistent mit den neueren Metric-Modulen.
• Edge-Cases: leer → alle Nullwerte; ein unique Token → H = 0, hill = 1.0 (= vocab_size).
• analyze_loo bewusst weggelassen: Entropie ist nichtlinear, also nicht trivial subtraktiv aus baseline. Block-Analyzer fällt sauber auf full re-run zurück (Fallback via function_exported?).

Test

test/codeqa/metrics/file/renyi_entropy_test.exs, Muster wie brevity_test.exs. 13 Tests:

• Edge: leer → Nullwerte; ein Token → H=0 über Spektrum, Hill=1.0
• Uniform (a b c d e f g h): renyi_0 == renyi_2, spectrum_slope == 0, alle Orders kollabieren, hill == vocab_size == 8
• Dominiert: großer spectrum_slope, Monotonie H₀ ≥ H₁ ≥ H₂ ≥ H_∞, hill_2 << vocab_size
• Contract: keys/0 deckt sich mit analyze/1-Output

Verify

• mix test — 904 Tests, 0 failures
• mix compile --warnings-as-errors clean
• mix format --check-formatted clean
• Block-Impact/Goldfile-Tests grün

[github-actions]

🟠 Code Health: C+ (63/100)

192 files · codeqa-action · 2026-06-06

Combined metric scores use cosine similarity: +1 = metric profile perfectly matches healthy pattern for this behavior, 0 = no signal, −1 = anti-pattern detected. Mapped to 0–100 using breakpoints (approx: ≥0.5→A, ≥0.2→B, ≥0.0→C, ≥−0.3→D, <−0.3→F); actual letter grades use the full 15-step scale.

%%{init: {'theme': 'neutral'}}%%
xychart-beta
    title "Code Health Scores"
    x-axis ["Readability", "Complexity", "Structure", "Duplication", "Naming", "Magic Numbers", "Combined Metrics"]
    y-axis "Score" 0 --> 100
    bar [94, 31, 88, 48, 96, 100, 65]

Loading

Readability       ███████████████████░   94  🟢 A
Complexity        ██████░░░░░░░░░░░░░░   31  🔴 D-
Structure         ██████████████████░░   88  🟢 A-
Duplication       ██████████░░░░░░░░░░   48  🟠 C-
Naming            ███████████████████░   96  🟢 A
Magic Numbers     ████████████████████  100  🟢 A
Combined Metrics  █████████████░░░░░░░   65  🔴 D

[github-actions]

🔍 Top Likely Issues (cosine similarity)

Most negative cosine = file's metric profile best matches this anti-pattern.

Behavior	Cosine	Score
dependencies.low_coupling	-0.56	-12.39
file_structure.single_responsibility	-0.51	-12.25
file_structure.line_count_under_300	-0.44	-9.39
code_smells.no_dead_code_after_return	-0.42	-33.65
scope_and_assignment.used_only_once	-0.42	-14.64
scope_and_assignment.shadowed_by_inner_scope	-0.34	-4.84
file_structure.line_length_under_120	-0.30	-8.33
scope_and_assignment.declared_close_to_use	-0.26	-1.45
code_smells.no_debug_print_statements	-0.24	-2.24
variable_naming.loop_var_is_single_letter	-0.23	3.58

🟢 Readability — A (94/100)

Codebase averages: flesch_adapted=97.85, fog_adapted=4.81, avg_tokens_per_line=9.50, avg_line_length=35.68

Metric	Value	Score
readability.flesch_adapted	97.85	100
readability.fog_adapted	4.81	100
readability.avg_tokens_per_line	9.50	72
readability.avg_line_length	35.68	100

🔴 Complexity — D- (31/100)

Codebase averages: difficulty=41.03, effort=231306.84, volume=4013.14, estimated_bugs=1.34

Metric	Value	Score
halstead.difficulty	41.03	42
halstead.effort	231306.84	0
halstead.volume	4013.14	46
halstead.estimated_bugs	1.34	47

🟢 Structure — A- (88/100)

Codebase averages: branching_density=0.14, mean_depth=3.86, avg_function_lines=8.26, max_depth=9.20, max_function_lines=19.85, variance=6.86, avg_param_count=1.15, max_param_count=2.04

Metric	Value	Score
branching.branching_density	0.14	76
indentation.mean_depth	3.86	88
function_metrics.avg_function_lines	8.26	89
indentation.max_depth	9.20	87
function_metrics.max_function_lines	19.85	100
indentation.variance	6.86	100
function_metrics.avg_param_count	1.15	100
function_metrics.max_param_count	2.04	100

🟠 Duplication — C- (48/100)

Codebase averages: redundancy=0.59, bigram_repetition_rate=0.54, trigram_repetition_rate=0.37

Metric	Value	Score
compression.redundancy	0.59	58
ngram.bigram_repetition_rate	0.54	38
ngram.trigram_repetition_rate	0.37	40

🟢 Naming — A (96/100)

Codebase averages: entropy=0.89, mean=6.65, variance=18.81, avg_sub_words_per_id=1.17

Metric	Value	Score
casing_entropy.entropy	0.89	100
identifier_length_variance.mean	6.65	100
identifier_length_variance.variance	18.81	85
readability.avg_sub_words_per_id	1.17	100

🟢 Magic Numbers — A (100/100)

Codebase averages: density=0.00

Metric	Value	Score
magic_number_density.density	0.00	100

🔴 Combined Metrics — D (65/100)

Category	Score	Grade
Code Smells	25	🔴 D-
Consistency	81	🟡 B+
Dependencies	19	🔴 E+
Documentation	83	🟡 B+
Error Handling	92	🟢 A-
File Structure	48	🟠 C-
Function Design	81	🟡 B+
Naming Conventions	90	🟢 A-
Scope And Assignment	28	🔴 D-
Testing	83	🟡 B+
Type And Value	89	🟢 A-
Variable Naming	74	🟡 B

🔴 Code Smells — D- (25/100)

Cosine similarity scores for 1 behaviors.

Behavior	Cosine	Score	Grade
no_dead_code_after_return	-0.42	25	D-

🟡 Consistency — B+ (81/100)

Cosine similarity scores for 1 behaviors.

Behavior	Cosine	Score	Grade
consistent_function_style	0.37	81	B+

🔴 Dependencies — E+ (19/100)

Cosine similarity scores for 1 behaviors.

Behavior	Cosine	Score	Grade
low_coupling	-0.56	19	E+

🟡 Documentation — B+ (83/100)

Cosine similarity scores for 3 behaviors.

Behavior	Cosine	Score	Grade
file_has_module_docstring	0.30	77	B
function_has_docstring	0.45	86	A-
docstring_is_nonempty	0.45	87	A-

🟢 Error Handling — A- (92/100)

Cosine similarity scores for 3 behaviors.

Behavior	Cosine	Score	Grade
error_message_is_descriptive	0.52	90	A-
does_not_swallow_errors	0.60	92	A-
returns_typed_error	0.69	94	A

🟠 File Structure — C- (48/100)

Cosine similarity scores for 5 behaviors.

Behavior	Cosine	Score	Grade
single_responsibility	-0.51	21	E+
line_count_under_300	-0.44	24	E+
line_length_under_120	-0.30	30	D-
has_consistent_indentation	0.26	74	B
no_magic_numbers	0.57	91	A-

🟡 Function Design — B+ (81/100)

Cosine similarity scores for 3 behaviors.

Behavior	Cosine	Score	Grade
is_less_than_20_lines	0.33	79	B+
no_magic_numbers	0.38	82	B+
has_verb_in_name	0.40	83	B+

🟢 Naming Conventions — A- (90/100)

Cosine similarity scores for 1 behaviors.

Behavior	Cosine	Score	Grade
function_name_is_not_single_word	0.50	90	A-

🔴 Scope And Assignment — D- (28/100)

Cosine similarity scores for 3 behaviors.

Behavior	Cosine	Score	Grade
used_only_once	-0.42	25	D-
shadowed_by_inner_scope	-0.34	28	D-
declared_close_to_use	-0.26	32	D-

🟡 Testing — B+ (83/100)

Cosine similarity scores for 2 behaviors.

Behavior	Cosine	Score	Grade
test_single_concept	0.27	74	B
test_name_describes_behavior	0.53	91	A-

🟢 Type And Value — A- (89/100)

Cosine similarity scores for 1 behaviors.

Behavior	Cosine	Score	Grade
hardcoded_url_or_path	0.49	89	A-

🟡 Variable Naming — B (74/100)

Cosine similarity scores for 1 behaviors.

Behavior	Cosine	Score	Grade
name_is_generic	0.26	74	B

[github-actions]

---

kind: refactoring-tasks
path: /home/runner/work/codeqa-action/codeqa-action
timestamp: 2026-06-06T15:24:58.342550Z
overall_grade: C+
overall_score: 63
task_count: 0
critical: 0
high: 0
instructions: >-
Address the tasks below in order of severity (critical first).
After each fix, run the project's test suite and confirm it passes
before moving on.

No critical or high-severity blocks need attention. ✅