Make score documentation more visible to the users. #506
Description
Current score is based on several different sub-score but their scope is unclear from the current documentation. Some are clear from their name e.g. "Duplication" while others ("File Health", "Elegance") are less clear. Furthermore the scores themselves have implicit assumptions with aggregation (elegance=mid+low+high elegance), some score being hidden from score cards, weights are also hidden from the user,... It would be nice to have a rough definition for each of them e.g. in the README.
Something like:
Mechanical Pool (25% of overall)
| Display name | Weight | Definition |
|---|---|---|
| File health | 2.0 | Large or deeply nested files that are hard to navigate and modify |
| Code quality | 1.0 | Code smells: unused variables, unreachable code, bad patterns |
| Duplication | 1.0 | Copy-pasted logic that should be deduplicated |
| Test health | 1.0 | Missing or weak test coverage on detectable paths |
| Security | 1.0 | Detectable security issues (injections, exposed secrets, unsafe patterns) |
Subjective Pool (75% of overall)
Per-file dimensions
Reviewed per file, reset on every scan (scores go stale and require re-review after code changes).
| Display name | Weight | Definition |
|---|---|---|
| High elegance | 22.0 | Top-level decomposition maps to domain capabilities; ownership and change boundaries are predictable |
| Mid elegance | 22.0 | Quality of handoffs across module/layer seams — explicit inputs/outputs, clean orchestration |
| Low elegance | 12.0 | Function and class internals are direct and precise — balanced extraction, bounded side effects |
| Contracts | 12.0 | Functions honor their stated contracts — no mutation in getters, no silent None when throws is documented |
| Type safety | 12.0 | Type annotations match runtime behavior — no lying return types, no Any where specific types exist |
| Abstraction fit | 8.0 | Abstractions earn their keep — no pass-through wrappers, no leaky facades, no single-impl interfaces |
| Logic clarity | 6.0 | Control flow does what it claims — no dead branches, redundant checks, or always-true conditions |
| Structure nav | 5.0 | Directory layout matches ownership — no stragglers at root, no import-affinity mismatches |
| Error consistency | 3.0 | Uniform error strategy across the codebase — no mixed throw/null/Result, no swallowed errors |
| Naming quality | 2.0 | Names communicate intent — no generic verbs, no name/behavior mismatches |
| AI generated debt | 1.0 | Absence of LLM-hallmark patterns — restating comments, defensive overengineering, copy-paste boilerplate |
Holistic dimensions
Reviewed at codebase level, not tied to individual files.
| Display name | Weight | Definition |
|---|---|---|
| Design coherence | 10.0 | Structural decisions are sound — focused functions, earned abstractions, consistent patterns |
| Cross-module arch | 1.0 | Dependency direction is sound — no cycles, no hub modules, no shared-mutable-state coordination |
| Init coupling | 1.0 | No boot-order dependencies — no import-time side effects, no global singleton creation-order issues |
| Convention drift | 1.0 | Naming and organization conventions are uniform — no snake_case islands in a camelCase codebase |
| Dep health | 1.0 | No duplicate libraries for the same purpose, no heavy deps for light use, no unused packages |
| Test strategy | 1.0 | Critical paths are covered; tests don't couple to implementation details or rely on timing |
| API coherence | 1.0 | Public API shapes are consistent — same parameter ordering, no mixed sync/async, no overloaded interfaces |
| Auth consistency | 1.0 | Auth/permission patterns applied uniformly — no sibling routes with auth on some but not others |
| Stale migration | 1.0 | No old+new API coexistence, no deprecated-but-still-called symbols, no lingering migration shims |
| Total (all 20) | 123.0 |