Add transparent library health engine

2026-06-30 17:47:54 -07:00
parent 167f029c28
commit b8bf9ec6e1
6 changed files with 155 additions and 1 deletions
@@ -0,0 +1,31 @@
+# Library Health Engine
+
+## Problem
+
+Raw missing-reference counts do not provide a compact view of library integrity,
+but an opaque blended score would imply confidence the current data cannot support.
+
+## Architecture
+
+The health engine produces an immutable report from the core `Library`. Its score
+is only the percentage of crate references resolved by exact filename. The report
+also exposes missing references, unique missing filenames, duplicate filename
+groups, extra duplicate files, unused tracks, and missing references with matching
+candidates.
+
+Duplicate, unused, and candidate counts are informational. They do not affect the
+score until the project has a documented and validated weighting policy. An empty
+library has no score rather than a misleading 0% or 100%.
+
+## Edge Cases
+
+- The same missing filename referenced by several crates.
+- Several disk files sharing a filename.
+- Conflict-suffixed files that are unused but may be match candidates.
+- Libraries with no crate references.
+- Tracks referenced by filename from more than one crate.
+
+## Verification
+
+Tests assert every metric, the disclosed score basis, candidate integration, and
+empty-library behavior. Analysis remains entirely read-only.