moult 0.1.0

data/lib/moult/health/score.rb

@@ -0,0 +1,291 @@
+# frozen_string_literal: true
+
+module Moult
+  module Health
+    # The pure model that turns the other analyses' signals into one composite
+    # health score. This slice's realisation of Moult's protected confidence API:
+    # it answers a deliberately humble question — *how healthy does this codebase
+    # look, given the signals we have* — and it is never a verdict. Every component
+    # records the observation behind its sub-score as a {Reason}, and the composite
+    # records which components contributed, so the number is auditable.
+    #
+    # {assess} is a pure function of small numeric inputs ({Inputs} and the per-
+    # analysis +*Input+ structs) — no IO, no report objects. That keeps it trivially
+    # unit-testable and lets the scoring be pinned against hand-built inputs: drift
+    # is a bug, the same treatment {ABC}, the coverage {Resolver}, and the
+    # duplication {Confidence} model get.
+    #
+    # The single inversion to keep in mind: the four input analyses all score
+    # *badness* (higher = worse). Health scores *goodness* (1.0 = healthy). Every
+    # normalisation converts a bounded badness ratio b in [0, 1] to a health
+    # sub-score via {health_from_badness} — the one audited inversion point.
+    module Score
+      # ---- pinned weights -----------------------------------------------------
+      # Static weight of each built-in component; they sum to 1.0 and are
+      # renormalised over whatever components are actually present. Complexity
+      # anchors the composite — it is the only signal that means something with no
+      # git history and no coverage. Coverage and dead code tie: both are strong
+      # "is this code used" signals but each is conditional. Duplication is the
+      # softest health signal (sometimes deliberate), so it gets the smallest share.
+      # Boundaries (conditional: only packwerk projects) joins as a structural signal;
+      # the original four kept their RELATIVE proportions (each scaled by 0.8) so a
+      # repo without boundaries scores and renormalises exactly as before.
+      WEIGHTS = {
+        "complexity" => 0.24,
+        "dead_code" => 0.20,
+        "duplication" => 0.16,
+        "coverage" => 0.20,
+        "boundaries" => 0.20
+      }.freeze
+
+      # ---- pinned grade thresholds (inclusive lower bounds on the composite) ---
+      # Letter grades on a normalised score follow the conventions of established
+      # code-health tools (Code Climate's A–F maintainability grade, SonarQube's
+      # A–E maintainability rating, CodeScene's 1–10 Code Health). The density/ratio
+      # normalisation below mirrors SonarQube's debt-RATIO approach (debt relative
+      # to size) rather than absolute counts. NOTE: the knees and weights here are
+      # v1 judgement-based heuristics chosen for sane, monotonic behaviour — they
+      # are NOT yet calibrated against a real-world baseline corpus the way CodeScene
+      # calibrates its factors; corpus calibration is deliberate future work. They
+      # are pinned so the SIGNAL is deterministic and auditable; treat drift as a bug.
+      GRADE_THRESHOLDS = [
+        ["A", 0.90],
+        ["B", 0.80],
+        ["C", 0.70],
+        ["D", 0.60],
+        ["F", 0.0]
+      ].freeze
+
+      # ---- pinned complexity normalisation ------------------------------------
+      # Health falls linearly as the MEAN per-file risk approaches a knee. Averaging
+      # over files already dilutes single outliers, so a plain ratio (à la SonarQube's
+      # debt ratio) is honest and predictable — no extra log compression, which would
+      # double-penalise moderate code.
+      COMPLEXITY_CHURN_KNEE = 300.0 # mean complexity*churn per file at which health hits the floor
+      COMPLEXITY_ONLY_KNEE = 150.0  # mean summed-ABC per file at which health hits the floor (no churn signal)
+      COMPLEXITY_FLOOR = 0.30       # complexity alone is a soft signal: never reads as 0.0 catastrophic
+
+      # ---- pinned dead-code normalisation -------------------------------------
+      DEADCODE_DENSITY_KNEE = 0.12   # confidence-weighted dead density at which health hits 0
+      DEADCODE_UNRESOLVED_CAP = 0.95 # an unresolved index cannot certify perfect health
+
+      # ---- pinned duplication normalisation -----------------------------------
+      DUPLICATION_BURDEN_KNEE = 40.0 # confidence-weighted duplicated mass per file at which health hits 0
+
+      # ---- pinned boundaries normalisation ------------------------------------
+      BOUNDARY_BURDEN_KNEE = 4.0 # severity-weighted boundary violations per file at which health hits 0
+
+      # One auditable observation behind a sub-score. Mirrors the rule/.../detail
+      # reason shape used across Moult, but health sub-scores are RATIOS not signed
+      # delta-sums, so it carries the observed +value+ (a [0, 1] quantity) rather
+      # than a +delta+. Kept local so the health slice does not couple to the
+      # dead-code or duplication Reason structs.
+      Reason = Struct.new(:rule, :value, :detail) do
+        def to_h
+          {rule: rule.to_s, value: value, detail: detail}
+        end
+      end
+
+      # A graded component: a health sub-score in [0, 1] (1.0 = healthy), the stats
+      # backing it, and the reasons behind it.
+      Component = Struct.new(:name, :category, :score, :stats, :reasons)
+
+      # The whole-codebase (or per-file) result: the composite + the present
+      # components. +score+/+grade+ are nil only when every component is absent.
+      Composite = Struct.new(:score, :grade, :components)
+
+      # IO-free numeric inputs. The orchestrator extracts one of each from the
+      # matching analysis report; the model never sees a report object. A nil slot
+      # means the analysis was absent or errored — it is dropped from the composite.
+      Inputs = Struct.new(:complexity, :dead_code, :duplication, :coverage, :boundaries)
+
+      ComplexityInput = Struct.new(:file_count, :total_complexity, :total_score, :churn_present)
+      DeadCodeInput = Struct.new(:symbol_count, :confidence_sum, :finding_count, :resolved)
+      DuplicationInput = Struct.new(:file_count, :weighted_dup_mass, :set_count)
+      CoverageInput = Struct.new(:hot, :cold)
+      BoundariesInput = Struct.new(:file_count, :weighted_violations, :violation_count)
+
+      module_function
+
+      # @param inputs [Inputs]
+      # @return [Composite]
+      def assess(inputs)
+        components = [
+          complexity_component(inputs.complexity),
+          dead_code_component(inputs.dead_code),
+          duplication_component(inputs.duplication),
+          coverage_component(inputs.coverage),
+          boundaries_component(inputs.boundaries)
+        ].compact
+
+        return Composite.new(score: nil, grade: nil, components: []) if components.empty?
+
+        total_weight = components.sum { |c| WEIGHTS.fetch(c.name) }
+        weighted = components.sum { |c| c.score * WEIGHTS.fetch(c.name) }
+        overall = (weighted / total_weight).round(2)
+
+        Composite.new(score: overall, grade: grade_for(overall), components: components)
+      end
+
+      # @param score [Float] composite in [0, 1]
+      # @return [String] letter grade
+      def grade_for(score)
+        GRADE_THRESHOLDS.find { |(_, low)| score >= low }.first
+      end
+
+      # The renormalised share a present component carried of the composite.
+      # @param name [String] component name
+      # @param present_names [Array<String>] names of the components that contributed
+      # @return [Float]
+      def normalized_weight(name, present_names)
+        total = present_names.sum { |n| WEIGHTS.fetch(n) }
+        return 0.0 if total.zero?
+        (WEIGHTS.fetch(name) / total).round(4)
+      end
+
+      # Convert a bounded badness ratio to a health sub-score, applying an optional
+      # floor so a soft signal never reads as catastrophic 0.0.
+      # @param badness [Float] in [0, 1] (clamped); higher = worse
+      # @param floor [Float] lowest the sub-score may reach
+      # @return [Float] rounded to 2 decimals
+      def health_from_badness(badness, floor: 0.0)
+        b = badness.clamp(0.0, 1.0)
+        ((1.0 - b) * (1.0 - floor) + floor).clamp(0.0, 1.0).round(2)
+      end
+
+      # @param input [ComplexityInput, nil]
+      # @return [Component, nil]
+      def complexity_component(input)
+        return nil unless input
+        return healthy_by_absence("complexity", "no methods with complexity to score") if input.file_count.to_i.zero?
+
+        if input.churn_present
+          mean_risk = input.total_score / input.file_count.to_f
+          badness = mean_risk / COMPLEXITY_CHURN_KNEE
+          reason = Reason.new(rule: :complexity_churn_density, value: nil,
+            detail: "mean complexity*churn per file #{mean_risk.round(1)} vs knee #{COMPLEXITY_CHURN_KNEE}")
+        else
+          mean_cx = input.total_complexity / input.file_count.to_f
+          badness = mean_cx / COMPLEXITY_ONLY_KNEE
+          reason = Reason.new(rule: :complexity_only_density, value: nil,
+            detail: "no churn signal; mean ABC per file #{mean_cx.round(1)} vs knee #{COMPLEXITY_ONLY_KNEE}")
+        end
+
+        score = health_from_badness(badness, floor: COMPLEXITY_FLOOR)
+        reason.value = score
+        Component.new(
+          name: "complexity", category: "complexity", score: score,
+          stats: {
+            file_count: input.file_count,
+            mean_complexity: (input.total_complexity / input.file_count.to_f).round(2),
+            churn_present: input.churn_present
+          },
+          reasons: [reason]
+        )
+      end
+
+      # @param input [DeadCodeInput, nil]
+      # @return [Component, nil]
+      def dead_code_component(input)
+        return nil unless input
+        return healthy_by_absence("dead_code", "no symbols to score") if input.symbol_count.to_i.zero?
+
+        density = input.confidence_sum / input.symbol_count.to_f
+        score = health_from_badness(density / DEADCODE_DENSITY_KNEE)
+        reasons = [Reason.new(rule: :dead_density, value: score,
+          detail: "confidence-weighted dead density #{density.round(4)} vs knee #{DEADCODE_DENSITY_KNEE} " \
+                  "(#{input.finding_count} candidates / #{input.symbol_count} symbols)")]
+
+        unless input.resolved
+          capped = [score, DEADCODE_UNRESOLVED_CAP].min
+          if capped < score
+            score = capped
+            reasons << Reason.new(rule: :index_unresolved, value: score,
+              detail: "index did not fully resolve; capped at #{DEADCODE_UNRESOLVED_CAP}")
+          end
+        end
+
+        Component.new(
+          name: "dead_code", category: "dead_code", score: score,
+          stats: {
+            symbol_count: input.symbol_count,
+            candidate_count: input.finding_count,
+            confidence_sum: input.confidence_sum.round(2),
+            resolved: input.resolved
+          },
+          reasons: reasons
+        )
+      end
+
+      # @param input [DuplicationInput, nil]
+      # @return [Component, nil]
+      def duplication_component(input)
+        return nil unless input
+        return healthy_by_absence("duplication", "no files to score") if input.file_count.to_i.zero?
+
+        burden = input.weighted_dup_mass / input.file_count.to_f
+        score = health_from_badness(burden / DUPLICATION_BURDEN_KNEE)
+        Component.new(
+          name: "duplication", category: "duplication", score: score,
+          stats: {
+            file_count: input.file_count,
+            weighted_dup_mass: input.weighted_dup_mass.round(1),
+            clone_sets: input.set_count
+          },
+          reasons: [Reason.new(rule: :duplication_burden, value: score,
+            detail: "confidence-weighted duplicated mass per file #{burden.round(2)} vs knee #{DUPLICATION_BURDEN_KNEE} " \
+                    "(#{input.set_count} clone sets)")]
+        )
+      end
+
+      # @param input [CoverageInput, nil]
+      # @return [Component, nil]
+      def coverage_component(input)
+        return nil unless input
+        tracked = input.hot.to_i + input.cold.to_i
+        # untracked is deliberately NOT in the denominator: it is no signal, so it
+        # must never count as either healthy or unhealthy.
+        return healthy_by_absence("coverage", "no tracked symbols (untracked carries no signal)") if tracked.zero?
+
+        cold_ratio = input.cold / tracked.to_f
+        score = health_from_badness(cold_ratio)
+        Component.new(
+          name: "coverage", category: "coverage", score: score,
+          stats: {hot: input.hot, cold: input.cold, tracked: tracked},
+          reasons: [Reason.new(rule: :cold_ratio, value: score,
+            detail: "#{input.cold} cold of #{tracked} tracked symbols (untracked excluded)")]
+        )
+      end
+
+      # @param input [BoundariesInput, nil]
+      # @return [Component, nil]
+      def boundaries_component(input)
+        return nil unless input
+        return healthy_by_absence("boundaries", "no files to score") if input.file_count.to_i.zero?
+
+        burden = input.weighted_violations / input.file_count.to_f
+        score = health_from_badness(burden / BOUNDARY_BURDEN_KNEE)
+        Component.new(
+          name: "boundaries", category: "architecture_boundary", score: score,
+          stats: {
+            file_count: input.file_count,
+            weighted_violations: input.weighted_violations.round(2),
+            violation_count: input.violation_count
+          },
+          reasons: [Reason.new(rule: :boundary_burden, value: score,
+            detail: "severity-weighted boundary violations per file #{burden.round(3)} vs knee #{BOUNDARY_BURDEN_KNEE} " \
+                    "(#{input.violation_count} violations)")]
+        )
+      end
+
+      # A present component that is vacuously healthy because it had nothing to
+      # score — distinct from an absent (nil) component, and it says why.
+      def healthy_by_absence(name, detail)
+        Component.new(
+          name: name, category: name, score: 1.0, stats: {},
+          reasons: [Reason.new(rule: :no_signal, value: 1.0, detail: detail)]
+        )
+      end
+    end
+  end
+end

data/lib/moult/health.rb

@@ -0,0 +1,320 @@
+# frozen_string_literal: true
+
+module Moult
+  # Orchestrates the health score: it runs each existing analysis, extracts the
+  # numeric signals each one exposes, and composes them through the pure
+  # {Health::Score} model into one auditable {HealthReport}. There is no external
+  # tool here — the "adapter" is this composition of Moult's own reports.
+  #
+  # This is the only layer that does IO and knows how the signals are sourced;
+  # {Score} stays a pure function of the extracted numbers so it can be pinned in
+  # isolation. Every analysis is run inside its own rescue: a failure degrades that
+  # one component to `present: false` with a diagnostic, never crashing the whole
+  # health run.
+  module Health
+    # Fixed component order, so output is stable and every slot is accounted for
+    # (present, skipped, or errored).
+    KNOWN_COMPONENTS = %w[complexity dead_code duplication coverage boundaries].freeze
+
+    # Cap on join keys serialized per file, so the roll-up cannot balloon on a
+    # large file; the true total is recorded alongside.
+    SYMBOLS_PER_FILE = 20
+
+    # The outcome of one isolated analysis run.
+    Run = Struct.new(:value, :error) do
+      def ok?
+        error.nil? && !value.nil?
+      end
+    end
+
+    module_function
+
+    # @param root [String] absolute analysis root
+    # @param files [Array<String>] absolute Ruby file paths to analyse
+    # @param index [Index] resolved definition/reference index (drives dead-code + coverage)
+    # @param rails [RailsConventions] Rails entrypoint awareness for dead-code
+    # @param coverage [Coverage::Dataset, nil] runtime coverage to merge (adds the coverage component)
+    # @param since [String, nil] churn window start for the complexity component
+    # @return [HealthReport]
+    def build_report(root:, files:, index:, rails:, coverage: nil, since: nil,
+      git_ref: nil, generated_at: nil, churn_window: nil, churn_since: nil)
+      churn = Churn.collect(root: root, since: since || Churn::DEFAULT_SINCE)
+
+      runs = {
+        "complexity" => run { Scoring.build_report(root: root, files: files, churn: churn) },
+        "dead_code" => run { DeadCode.build_report(root: root, files: files, index: index, rails: rails, coverage: coverage) },
+        "duplication" => run { Duplication.build_report(root: root, files: files) },
+        "coverage" => run { coverage ? CoverageReport.build(index: index, coverage: coverage, root: root) : nil },
+        "boundaries" => run { Boundaries.build_report(root: root) }
+      }
+
+      # Derive churn presence from the JOINED hotspots, not the raw churn hash: a
+      # repo-relative churn map run against a subdir root won't join to the scored
+      # files, so the honest signal is "did any scored file actually carry churn".
+      churn_present = runs["complexity"].ok? &&
+        runs["complexity"].value.hotspots.any? { |h| h.churn.to_i.positive? }
+
+      inputs = Score::Inputs.new(
+        complexity: runs["complexity"].ok? ? complexity_input(runs["complexity"].value, churn_present) : nil,
+        dead_code: runs["dead_code"].ok? ? dead_code_input(runs["dead_code"].value, index) : nil,
+        duplication: runs["duplication"].ok? ? duplication_input(runs["duplication"].value, files.size) : nil,
+        coverage: runs["coverage"].ok? ? coverage_input(runs["coverage"].value) : nil,
+        # Absent (skipped) unless the project is actually packwerk-configured: an
+        # unconfigured repo has no boundary signal and must not read as healthy 1.0.
+        boundaries: boundaries_present?(runs["boundaries"]) ? boundaries_input(runs["boundaries"].value, files.size) : nil
+      )
+
+      composite = Score.assess(inputs)
+      components = component_views(composite, runs, coverage_requested: !coverage.nil?)
+      files_view = file_rollup(runs, index, churn_present)
+
+      HealthReport.new(
+        root: root,
+        score: composite.score,
+        grade: composite.grade,
+        components: components,
+        files: files_view,
+        git_ref: git_ref,
+        generated_at: generated_at,
+        coverage_source: coverage&.source,
+        churn_window: churn_window,
+        churn_since: churn_since
+      )
+    end
+
+    # Run one analysis in isolation: success carries the report, any failure
+    # carries the message so the component degrades rather than the whole run.
+    def run
+      Run.new(value: yield, error: nil)
+    rescue => e
+      Run.new(value: nil, error: e.message)
+    end
+
+    # ---- signal extraction (heavy report -> pure numeric input) ---------------
+
+    def complexity_input(report, churn_present)
+      hs = report.hotspots
+      Score::ComplexityInput.new(
+        file_count: hs.size,
+        total_complexity: hs.sum(&:complexity),
+        total_score: hs.sum(&:score),
+        churn_present: churn_present
+      )
+    end
+
+    def dead_code_input(report, index)
+      Score::DeadCodeInput.new(
+        symbol_count: index.definitions.size,
+        confidence_sum: report.findings.sum(&:confidence),
+        finding_count: report.findings.size,
+        resolved: report.resolved
+      )
+    end
+
+    def duplication_input(report, file_count)
+      # Only the EXTRA copies are consolidatable mass; confidence-weight so a
+      # low-confidence "similar" rhyme barely registers.
+      weighted = report.findings.sum { |f| f.confidence * f.mass * (f.occurrences.size - 1) }
+      Score::DuplicationInput.new(
+        file_count: file_count,
+        weighted_dup_mass: weighted,
+        set_count: report.findings.size
+      )
+    end
+
+    def coverage_input(report)
+      s = report.summary
+      Score::CoverageInput.new(hot: s[:hot], cold: s[:cold])
+    end
+
+    # A boundaries run contributes only when it ran AND the project is packwerk-
+    # configured; an unconfigured repo yields a successful-but-empty report that
+    # must be SKIPPED, not scored as vacuously healthy.
+    def boundaries_present?(run)
+      run.ok? && run.value.configured
+    end
+
+    def boundaries_input(report, file_count)
+      Score::BoundariesInput.new(
+        file_count: file_count,
+        weighted_violations: report.findings.sum { |f| boundary_weight(f) * f.occurrences.size },
+        violation_count: report.findings.sum { |f| f.occurrences.size }
+      )
+    end
+
+    def boundary_weight(finding)
+      Boundaries::Severity::SEVERITY_WEIGHT.fetch(finding.severity, Boundaries::Severity::SEVERITY_WEIGHT.fetch("low"))
+    end
+
+    # ---- component views (every slot, present or not) -------------------------
+
+    def component_views(composite, runs, coverage_requested:)
+      present = composite.components.to_h { |c| [c.name, c] }
+      present_names = composite.components.map(&:name)
+
+      KNOWN_COMPONENTS.map do |name|
+        component = present[name]
+        if component
+          HealthReport::ComponentView.new(
+            name: name,
+            category: component.category,
+            present: true,
+            score: component.score,
+            weight: Score::WEIGHTS.fetch(name),
+            normalized_weight: Score.normalized_weight(name, present_names),
+            summary: component.stats,
+            reasons: component.reasons,
+            diagnostic: nil
+          )
+        else
+          HealthReport::ComponentView.new(
+            name: name,
+            category: nil,
+            present: false,
+            score: nil,
+            weight: Score::WEIGHTS.fetch(name),
+            normalized_weight: nil,
+            summary: {},
+            reasons: [],
+            diagnostic: diagnostic_for(name, runs[name], coverage_requested)
+          )
+        end
+      end
+    end
+
+    def diagnostic_for(name, run, coverage_requested)
+      return run.error if run&.error
+      case name
+      when "coverage"
+        coverage_requested ? "coverage produced no usable signal" : "no --coverage supplied"
+      when "boundaries"
+        "not a packwerk project (no packwerk.yml)"
+      else
+        "analysis produced no result"
+      end
+    end
+
+    # ---- per-file roll-up (the cross-analysis join surface) -------------------
+
+    def file_rollup(runs, index, churn_present)
+      hotspots = runs["complexity"].ok? ? runs["complexity"].value.hotspots.to_h { |h| [h.path, h] } : {}
+      dead = runs["dead_code"].ok? ? runs["dead_code"].value.findings.group_by(&:path) : {}
+      dup = runs["duplication"].ok? ? clones_by_path(runs["duplication"].value) : {}
+      cov = runs["coverage"].ok? ? coverage_by_path(runs["coverage"].value) : {}
+      bnd = boundaries_present?(runs["boundaries"]) ? boundaries_by_path(runs["boundaries"].value) : {}
+      symbols_per_file = index.definitions.group_by(&:path).transform_values(&:size)
+
+      paths = Set.new
+      paths.merge(hotspots.keys)
+      paths.merge(dead.keys)
+      paths.merge(dup.keys)
+      paths.merge(cov.select { |_, c| c[:cold].positive? }.keys)
+      paths.merge(bnd.keys)
+
+      views = paths.map do |path|
+        file_view(path, hotspots[path], dead[path], dup[path], cov[path], bnd[path],
+          symbols_per_file[path], churn_present)
+      end
+      # Least-healthy first, path as a deterministic tie-break.
+      views.sort_by { |v| [v.score, v.path] }
+    end
+
+    def file_view(path, hotspot, dead_findings, clone, coverage, boundaries, symbol_count, churn_present)
+      inputs = Score::Inputs.new(
+        complexity: hotspot && Score::ComplexityInput.new(
+          file_count: 1, total_complexity: hotspot.complexity,
+          total_score: hotspot.score, churn_present: churn_present
+        ),
+        dead_code: dead_findings && Score::DeadCodeInput.new(
+          symbol_count: [symbol_count.to_i, dead_findings.size].max,
+          confidence_sum: dead_findings.sum(&:confidence),
+          finding_count: dead_findings.size, resolved: true
+        ),
+        duplication: clone && Score::DuplicationInput.new(
+          file_count: 1, weighted_dup_mass: clone[:weighted_mass], set_count: clone[:sets]
+        ),
+        coverage: coverage && tracked?(coverage) && Score::CoverageInput.new(
+          hot: coverage[:hot], cold: coverage[:cold]
+        ),
+        boundaries: boundaries && Score::BoundariesInput.new(
+          file_count: 1, weighted_violations: boundaries[:weighted], violation_count: boundaries[:count]
+        )
+      )
+
+      composite = Score.assess(inputs)
+      ids = file_symbol_ids(hotspot, dead_findings, clone, coverage)
+      HealthReport::FileView.new(
+        path: path,
+        score: composite.score,
+        grade: composite.grade,
+        components: composite.components.to_h { |c| [c.name, c.score] },
+        symbol_ids: ids.first(SYMBOLS_PER_FILE),
+        symbol_count: ids.size
+      )
+    end
+
+    # Contributing join keys for a file, dead-finding / clone / coverage / hotspot
+    # in that order, de-duplicated.
+    def file_symbol_ids(hotspot, dead_findings, clone, coverage)
+      ids = []
+      ids.concat(dead_findings.map(&:symbol_id)) if dead_findings
+      ids.concat(clone[:symbol_ids]) if clone
+      ids.concat(coverage[:cold_ids]) if coverage
+      ids.concat(hotspot.methods.map(&:symbol_id)) if hotspot
+      ids.compact.uniq
+    end
+
+    def tracked?(coverage)
+      (coverage[:hot] + coverage[:cold]).positive?
+    end
+
+    # path => {weighted_mass:, sets:, symbol_ids:} from clone occurrences in that file.
+    def clones_by_path(report)
+      acc = Hash.new { |h, k| h[k] = {weighted_mass: 0.0, sets: 0, symbol_ids: []} }
+      report.findings.each do |finding|
+        finding.occurrences.each do |occ|
+          bucket = acc[occ.path]
+          bucket[:weighted_mass] += finding.confidence * finding.mass
+          bucket[:sets] += 1
+          bucket[:symbol_ids] << occ.symbol_id if occ.symbol_id
+        end
+      end
+      acc.default_proc = nil # so later missing-key reads return nil instead of mutating
+      acc
+    end
+
+    # path => {weighted:, count:} from boundary-violation occurrences in that file.
+    # Boundary occurrences carry a null symbol_id (file-keyed), so they contribute to
+    # the per-file roll-up at PATH granularity only — never to file_symbol_ids.
+    def boundaries_by_path(report)
+      acc = Hash.new { |h, k| h[k] = {weighted: 0.0, count: 0} }
+      report.findings.each do |finding|
+        weight = boundary_weight(finding)
+        finding.occurrences.each do |occ|
+          acc[occ.path][:weighted] += weight
+          acc[occ.path][:count] += 1
+        end
+      end
+      acc.default_proc = nil # so later missing-key reads return nil instead of mutating
+      acc
+    end
+
+    # path => {hot:, cold:, cold_ids:} from coverage entries (path parsed from symbol_id).
+    def coverage_by_path(report)
+      acc = Hash.new { |h, k| h[k] = {hot: 0, cold: 0, cold_ids: []} }
+      report.entries.each do |entry|
+        path = entry.symbol_id.split(":", 3).first
+        case entry.runtime
+        when :hot then acc[path][:hot] += 1
+        when :cold
+          acc[path][:cold] += 1
+          acc[path][:cold_ids] << entry.symbol_id
+        end
+      end
+      acc.default_proc = nil # so later missing-key reads return nil instead of mutating
+      acc
+    end
+  end
+end
+
+require_relative "health/score"