hayaoki 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 70201420261ecfa6d0995fe4d99998a2790c33ab4569bbc80055a99eec4a6720
+  data.tar.gz: 5b4fba65fef01f18828f28efba572a4aa683625b307f4d11041b528332f794c5
+SHA512:
+  metadata.gz: f6bea9fe2b633032130e6fc71ac051d7f9d65f98282af7edc357bdaec8c2860ff6fa1fc2f1d8bee3203c527a08ac2db6597d1786be0082d3ea0d4593c9ed0143
+  data.tar.gz: 85fb1950f0d0c82caf684d00c16dff4b94d6e30fd6914144f7dc298071fde7a758580f89dd23261bb52bfe29bceb473eace37786a62d070fecc5f385a57e7e68

data/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+## [0.1.0] - 2026-11-08
+
+- `hayaoki boot-report` measures boot time over several runs and reports the median and range, in text, JSON, or speedscope format.
+- The probe, injected with `ruby -r`, records require, require_relative, load, initializer, on_load, eager_load, `Bundler.require`, and `initialize!` as spans.
+- `config.eager_load_namespaces` entries (e.g. `TZInfo.eager_load!`) are recorded as eager_load spans and attributed to the gem that defines them, instead of disappearing into the `eager_load!` initializer body.
+- Requires are matched to loaded files for `./x`, `../x`, `x.so` (loaded as `.bundle` on macOS) and built-in extensions such as `prism/prism.so`. Before, these fell back to the last loaded file, which could be another thread's. Remaining fallbacks are counted and reported as a warning.
+- Before measuring, the child `ruby` is checked to be Ruby 3.2 or later, with a one-line error that points to `--ruby` otherwise.
+- Phase breakdown (vm boot, bundler require, initialize) and per-gem and per-initializer rankings.
+- Improvement suggestions, printed as candidates: bootsnap effectiveness, heavy app initializers, unused heavy gems, dev gems in production, and eager load trade-offs. Disable with `--no-suggestions`.
+- `tzinfo_eager_load` suggestion: `TZInfo.eager_load!` takes 200–330 ms in Linux containers (see `bench/tzinfo_eager_load.rb`), and it can be made lazy with one line.
+- `devise_reload_routes` and `controller_action_methods` suggestions, measured on Mastodon and Redmine with `bench/boot_variants.rb`.
+- A ranking of `config.eager_load_namespaces` entries in the text output, and `eager_namespaces` in the JSON output.
+- Options for runs, environment, bootsnap mode (`warm`, `cold`, `both`), entry file, timeout, output file, and rows per ranking, plus thresholds for suggestions.
+- The probe has no runtime dependencies and writes JSON with its own encoder.
+- `--redact` replaces absolute paths in the output (text, JSON, and speedscope): the app directory with `<app>`, gem paths (including bundler git gems) with `<gem:name>/`, and the home directory with `~`.
+- A category table in the text and JSON output, with an `unattributed` row (boot time minus attributed self time) so the totals add up.
+- Applications that are themselves gems (`gemspec`, engine dummy apps, `path: "."`) are categorized as `app` for files under `app`, `config`, `lib`, and `db`.
+- JSON output omits the stderr of failed runs, which may contain secrets. It keeps the message, exit status, and error class.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Takato Hano
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,118 @@
+# hayaoki
+
+Wake your Rails app up early: find out where its boot time goes, and what to change.
+
+*hayaoki* (早起き) means "getting up early" in Japanese. It is a diagnostic tool: it measures and explains boot time, and does not make boot faster just by being installed.
+
+hayaoki measures where a Rails application's boot time goes and reports it by phase, by gem, and by initializer. The current release provides `hayaoki boot-report`.
+
+## Installation
+
+```sh
+gem install hayaoki
+```
+
+hayaoki is a standalone command. You do not need to add it to your Gemfile.
+
+## Usage
+
+```sh
+hayaoki boot-report [APP_DIR]
+```
+
+`APP_DIR` defaults to the current directory.
+
+| Option | Description |
+| --- | --- |
+| `--runs N` | number of measured runs (default 5) |
+| `--env ENV` | `RAILS_ENV` (default `production`) |
+| `--bootsnap MODE` | `warm`, `cold`, or `both` (default `warm`) |
+| `--ruby PATH` | ruby executable (default `ruby`) |
+| `--entry PATH` | boot entry file (default `config/environment`) |
+| `--timeout SEC` | per-run timeout in seconds (default 120) |
+| `--format FORMAT` | `text`, `json`, or `speedscope` (default `text`) |
+| `--output FILE` | write to FILE instead of stdout |
+| `--top N` | rows per ranking (default 10) |
+| `--no-suggestions` | do not print improvement suggestions |
+| `--initializer-threshold MS` | app initializer threshold for suggestions (default 50) |
+| `--gem-threshold MS` | gem self time threshold for suggestions (default 30) |
+| `--redact` | replace absolute paths in the output (all formats): the app directory (and its realpath) with `<app>`, gem paths with `<gem:name>/`, the home directory with `~` |
+| `--version` | show version |
+| `-h`, `--help` | show help |
+
+Example output:
+
+```
+total[warm]: 687.8 ms [684.3-699.4]
+Phases (median)
+  vm boot                █                            28.2 ms
+  bundler require        ████████                     195.6 ms
+  initialize             ███████████                  267.0 ms
+```
+
+## Suggestions
+
+| Rule | Confidence | What it looks for |
+| --- | --- | --- |
+| `dev_gems_in_production` | high / medium / low | development or test gems loaded in production (high: direct and not in a group; low: transitive) |
+| `bootsnap_ineffective` | high | bootsnap missing, or its cache not helping |
+| `heavy_app_initializer` | medium | app initializers slower than `--initializer-threshold` |
+| `tzinfo_eager_load` | medium | `TZInfo.eager_load!` loading every time zone at boot (see below) |
+| `devise_reload_routes` | medium (Devise 5+) / low | Devise reloading the routes before eager loading; they are loaded again later in boot |
+| `controller_action_methods` | low | `AbstractController.eager_load!` computing `action_methods` for every controller at boot |
+| `unused_heavy_gem` | low | heavy gems with no references in app code (candidates for `require: false`) |
+| `eager_load_tradeoff` | info | eager loading taking a large share of boot |
+
+Estimated savings are upper bounds. Findings can overlap, and the output marks which ones do, so do not add them up.
+
+### TZInfo eager loading
+
+In production, Rails 7.2 and later add `TZInfo` to `config.eager_load_namespaces`, and `TZInfo.eager_load!` reads all ~600 time zones at boot. Measured with [`bench/tzinfo_eager_load.rb`](https://github.com/TakatoHano/hayaoki/blob/main/bench/tzinfo_eager_load.rb) (median of 7 fresh processes on a GitHub-hosted runner, Ruby 3.4):
+
+| Environment | `TZInfo.eager_load!` |
+| --- | --- |
+| `ruby:3.4-slim`, system zoneinfo / with `tzinfo-data` | 243 ms / 194 ms |
+| `ruby:3.4-alpine` + `tzdata` / with `tzinfo-data` | 330 ms / 228 ms |
+| AWS Lambda `ruby:3.4`, system zoneinfo / with `tzinfo-data` | 319 ms / 202 ms |
+| macOS (Apple silicon, local) | 112 ms |
+
+Removing it (`Rails.application.config.eager_load_namespaces.delete(TZInfo)` in an initializer) leaves 5–15 ms at boot. Each zone is then loaded on first use, in under 1 ms. The trade-off is that forking servers no longer share the zone data copy-on-write.
+
+### Measured on real applications
+
+[`bench/boot_variants.rb`](https://github.com/TakatoHano/hayaoki/blob/main/bench/boot_variants.rb) boots an application with one setting changed at a time (median of fresh processes, GitHub-hosted runner, official Docker images, `RAILS_ENV=production`). The `real-apps` workflow runs it. Boot times vary by several hundred ms between runners, so compare within one run.
+
+| Change | Mastodon 4.7.5 | Redmine 7.0 | Cost moved to later |
+| --- | --- | --- | --- |
+| `eager_load_namespaces.delete(TZInfo)` | −128 ms | −193 to −328 ms | under 1 ms per zone used |
+| Devise `config.reload_routes = false` | −194 ms | (no Devise) | none: the routes are loaded once, later in boot |
+| `eager_load_namespaces.delete(AbstractController)` | −201 ms | −31 ms | 217 ms in total across 336 controllers, about 0.65 ms on each controller's first request |
+| `eager_load_namespaces.delete(I18n)` | −108 ms | −286 ms | 182 ms / 317 ms on the first translation |
+| `config.i18n.available_locales = [:en]` | no gain | no gain | every locale file is still parsed |
+
+hayaoki has no I18n suggestion: making it lazy only moves the whole cost to the first translation, which nearly every request needs.
+
+## How it works
+
+hayaoki runs your application in a child process with a probe injected through `ruby -r`. The probe hooks the require family of methods with an alias chain, not `prepend`, so it coexists with bootsnap, Zeitwerk, and bundled_gems. Rails-specific hooks (initializers, on_load hooks, eager loading, `Bundler.require`, and `initialize!`) are installed lazily, when the corresponding file is loaded. The measured overhead is about 2%.
+
+The design is described in [docs/design/probe.md](https://github.com/TakatoHano/hayaoki/blob/main/docs/design/probe.md).
+
+## Notes
+
+- The application is booted with the `ruby` found on `PATH` in the application directory (so rbenv, asdf, or mise pick the app's version), or with `--ruby PATH`. It must be Ruby 3.2 or later; hayaoki checks this before measuring.
+- By default hayaoki boots the application with `RAILS_ENV=production`. Boot may then need access to external services or credentials. If so, use `SECRET_KEY_BASE_DUMMY=1` for a dummy secret key, and `--env` to choose another environment.
+- Suggestions are candidates. Verify each one before applying it.
+- Output contains absolute paths unless you pass `--redact`. `--redact` rewrites paths only. It does not remove other content, so review the output before sharing it.
+- JSON output does not include the stderr of failed runs, because it may contain secrets. It keeps the error message, exit status, and error class. When every run fails, hayaoki prints the stderr tail to the terminal.
+- The category table (`gem`, `app`, `stdlib`, `other`, `init_body`, `unattributed`) sums to boot time. `init_body` is the own time of initializer blocks (not blamed on the gem that defines them). `unattributed` is boot time minus the self time attributed to files, initializer bodies, and on_load hooks. It covers time in `run_load_hooks` itself, the self time of phase and Zeitwerk eager load spans, and time outside any span. Background-thread spans are excluded.
+
+## Requirements
+
+- Ruby 3.2 or later
+- Rails 7.0 or later
+- macOS or Linux
+
+## License
+
+MIT. See [LICENSE](LICENSE).

data/exe/hayaoki

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "hayaoki/cli"
+
+exit Hayaoki::CLI.start(ARGV)

data/lib/hayaoki/boot_report/advisor.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require_relative "rules/base"
+
+module Hayaoki
+  module BootReport
+    # 改善候補 1 件。evidence は String キーの Hash の配列。
+    Suggestion = Struct.new(:rule, :confidence, :title, :evidence, :estimated_savings_ms, :action, :id, :overlaps, keyword_init: true) do
+      # 各 finding の節約見込みは重複しうるので足し算では出さず、上限 (単純和) として扱う。
+      def self.savings_upper_bound(list)
+        v = list.filter_map(&:estimated_savings_ms)
+        v.empty? ? nil : v.sum.round(1)
+      end
+
+      def to_h
+        { "id" => id, "overlaps" => Array(overlaps), "rule" => rule.to_s, "confidence" => confidence.to_s, "title" => title, "evidence" => evidence,
+          "estimated_savings_ms" => estimated_savings_ms, "action" => action }
+      end
+    end
+
+    # Report (と RunResult) から Suggestion を作る。ルールの例外は警告にして続行する。
+    class Advisor
+      CONFIDENCE_ORDER = %i[high medium low info].freeze
+      DEFAULT_INITIALIZER_THRESHOLD_MS = 50
+      DEFAULT_GEM_THRESHOLD_MS = 30
+
+      attr_reader :warnings
+
+      def self.rules
+        require_relative "rules/dev_gems_in_production"
+        require_relative "rules/bootsnap_ineffective"
+        require_relative "rules/heavy_app_initializer"
+        require_relative "rules/unused_heavy_gem"
+        require_relative "rules/eager_load_tradeoff"
+        require_relative "rules/tzinfo_eager_load"
+        require_relative "rules/devise_reload_routes"
+        require_relative "rules/controller_action_methods"
+        [Rules::DevGemsInProduction, Rules::BootsnapIneffective, Rules::HeavyAppInitializer,
+         Rules::UnusedHeavyGem, Rules::EagerLoadTradeoff, Rules::TzinfoEagerLoad,
+         Rules::DeviseReloadRoutes, Rules::ControllerActionMethods]
+      end
+
+      def initialize(report, app_dir:, result: nil, initializer_threshold_ms: DEFAULT_INITIALIZER_THRESHOLD_MS,
+                     gem_threshold_ms: DEFAULT_GEM_THRESHOLD_MS, rules: self.class.rules)
+        @ctx = Context.new(report: report, app_dir: app_dir, result: result,
+                           initializer_threshold_ms: initializer_threshold_ms, gem_threshold_ms: gem_threshold_ms)
+        @rules = rules
+        @warnings = []
+      end
+
+      def suggestions
+        @suggestions ||= run
+      end
+
+      private
+
+      def run
+        out = @rules.flat_map do |klass|
+          Array(klass.new(@ctx).call)
+        rescue StandardError, NotImplementedError => e
+          id = klass.respond_to?(:rule_id) ? klass.rule_id : klass.to_s
+          @warnings << "suggestion rule #{id} failed: #{e.class}: #{e.message}"[0, 300]
+          []
+        end
+        sorted = out.each_with_index.sort_by { |s, i| [CONFIDENCE_ORDER.index(s.confidence) || 99, -(s.estimated_savings_ms || 0), i] }.map(&:first)
+        mark_overlaps(sorted)
+      end
+
+      GEM_EVIDENCE_KEY = { dev_gems_in_production: "name", unused_heavy_gem: "gem" }.freeze
+      GEM_RULES = GEM_EVIDENCE_KEY.keys.freeze
+
+      # id を振り、節約見込みが重なりうる finding を overlaps に載せる。
+      #  - 同じ gem を別ルールが指している
+      #  - app initializer の inclusive 時間には gem の require が含まれうるので、gem 系の finding と重なる
+      #  - TZInfo.eager_load! などの時間は eager_load フェーズに含まれる
+      def mark_overlaps(list)
+        seen = Hash.new(0)
+        list.each do |s|
+          seen[s.rule] += 1
+          s.id = seen[s.rule] == 1 ? s.rule.to_s : "#{s.rule}##{seen[s.rule]}"
+        end
+        gems = {}.compare_by_identity
+        list.each { |s| gems[s] = gem_subjects(s) }
+        list.each do |s|
+          s.overlaps = list.filter_map do |o|
+            next if o.equal?(s)
+            o.id if (gems[s] & gems[o]).any? || initializer_vs_gem?(s, o) || eager_phase_pair?(s, o)
+          end
+        end
+        list
+      end
+
+      # eager_load フェーズの中の処理を指す finding は、eager_load_tradeoff と節約見込みが重なる
+      EAGER_PHASE_RULES = %i[tzinfo_eager_load controller_action_methods].freeze
+
+      def eager_phase_pair?(a, b)
+        pair = [a.rule, b.rule]
+        pair.include?(:eager_load_tradeoff) && pair.any? { |r| EAGER_PHASE_RULES.include?(r) }
+      end
+
+      def initializer_vs_gem?(a, b)
+        pair = [a.rule, b.rule]
+        pair.include?(:heavy_app_initializer) && pair.any? { |r| GEM_RULES.include?(r) }
+      end
+
+      def gem_subjects(s)
+        key = GEM_EVIDENCE_KEY[s.rule]
+        return [] unless key
+        Array(s.evidence).filter_map { |e| e[key] if e.is_a?(Hash) }
+      end
+    end
+  end
+end

data/lib/hayaoki/boot_report/aggregator.rb

@@ -0,0 +1,367 @@
+# frozen_string_literal: true
+
+require_relative "report"
+
+module Hayaoki
+  module BootReport
+    # probe の payload (Runner が集めた複数回分) を、設計書 §3.4 の正規化をかけた木にして集計する。
+    # 時間はすべて ms。各指標は { "median", "min", "max" } (偶数個なら中央2つの平均)。
+    class Aggregator
+      K_REQ = 0; K_RR = 1; K_LOAD = 2; K_INIT = 3; K_ONLOAD = 4; K_HOOKS = 5; K_EAGER = 6; K_PHASE = 7
+
+      Span = Struct.new(:idx, :kind, :name, :parent, :t0, :t1, :res, :tid, :cpu, :children, :incomplete, :merged, :owner) do
+        def require_kind? = kind <= K_LOAD
+        def dur_us = t1 - t0
+        def raised? = res == "raised"
+        # require 系は feature (res)。raised や非 String は nil
+        def feature = require_kind? && res.is_a?(String) && !raised? ? res : nil
+      end
+
+      Owner = Struct.new(:category, :name) # category: "gem" / "app" / "stdlib" / "other"
+
+      def initialize(top_files: 30, top_initializers: 30, top_on_loads: 30)
+        @top_files = top_files
+        @top_initializers = top_initializers
+        @top_on_loads = top_on_loads
+      end
+
+      # RunResult → { condition(String) => Report }
+      def aggregate_result(result)
+        result.payloads.to_h do |cond, list|
+          [cond, aggregate(list, condition: cond, meta: result.meta)]
+        end
+      end
+
+      def aggregate(payloads, condition: nil, meta: {})
+        ok, bad = payloads.partition { |p| p["status"] == "ok" }
+        warnings = Array(meta["warnings"]).dup
+        warnings << "#{bad.size} failed run(s) excluded from aggregation" unless bad.empty?
+        warnings.concat(ok.flat_map { |p| Array(p["probe_warnings"]) + Array(p["probe_errors"]).map { |e| "probe error: #{e}" } }.uniq)
+        fb = ok.map { |p| p.dig("resolve_fallbacks", "count").to_i }.max.to_i
+        if fb.positive?
+          ex = ok.flat_map { |p| Array(p.dig("resolve_fallbacks", "examples")) }.uniq.first(5)
+          warnings << "#{fb} require(s) could not be matched to a loaded file and were attributed to the last loaded file; " \
+                      "attribution may be off (e.g. #{ex.join(", ")})"
+        end
+        analyses = ok.map { |p| analyze(p) }
+        thread_spans = analyses.map { |a| a[:background_spans] }.max.to_i
+        warnings << "#{thread_spans} span(s) recorded on background threads; attribution is approximate and they are excluded from totals" if thread_spans.positive?
+        merged = analyses.sum { |a| a[:merged] }
+
+        Report.new(
+          condition: condition, runs: ok.size, failed: bad.size,
+          ruby: ok.first && ok.first["ruby"], features: stat(analyses.map { |a| a[:features] }),
+          phases: phases(analyses),
+          categories: keyed_stats(analyses.map { |a| a[:categories] }, order_by: "self_ms"),
+          gems: gems(analyses),
+          files: files(analyses),
+          initializers: initializers(analyses),
+          app_initializer_times: app_initializer_times(analyses),
+          on_loads: on_loads(analyses),
+          eager_namespaces: eager_namespaces(analyses),
+          false_require: {
+            "count" => stat(analyses.map { |a| a[:false_count] }), "time_ms" => stat(analyses.map { |a| a[:false_ms] })
+          },
+          threads: { "background_spans" => thread_spans, "merged_duplicates" => merged },
+          meta: meta, warnings: warnings.uniq
+        )
+      end
+
+      # 1 回分の payload を解析する。テストや formatter 用に公開しておく。
+      def analyze(payload)
+        spans = build_spans(payload)
+        merged = normalize!(spans)
+        spans = spans.reject(&:merged)
+        resolver = OwnerResolver.new(payload)
+        main = spans.select { |s| s.tid.to_i == 0 }
+        pmap = spans.to_h { |s| [s.idx, s] }
+        main.each { |s| s.owner = owner_of(s, resolver) }
+        selfs = {}
+        spans.each { |s| selfs[s] = s.dur_us - s.children.sum { |c| c.dur_us } }
+
+        a = {
+          merged: merged, features: payload["features"], background_spans: spans.size - main.size,
+          false_count: payload.dig("false_require", "count").to_i, false_ms: payload.dig("false_require", "time_us").to_i / 1000.0,
+          gems: Hash.new { |h, k| h[k] = { "self_ms" => 0.0, "require_ms" => 0.0, "on_load_ms" => 0.0, "eager_ms" => 0.0, "initializer_count" => 0, "category" => nil } },
+          categories: Hash.new { |h, k| h[k] = { "self_ms" => 0.0 } },
+          files: Hash.new { |h, k| h[k] = { "self_ms" => 0.0, "inclusive_ms" => 0.0, "owner" => nil, "category" => nil, "count" => 0 } },
+          initializers: Hash.new { |h, k| h[k] = { "inclusive_ms" => 0.0, "init_body_ms" => 0.0 } },
+          on_loads: Hash.new { |h, k| h[k] = { "inclusive_ms" => 0.0, "self_ms" => 0.0 } },
+          eager_namespaces: Hash.new { |h, k| h[k] = { "inclusive_ms" => 0.0, "self_ms" => 0.0 } },
+          phase: {}
+        }
+        spawn_at = payload["spawn_at"]&.to_f
+        boot_us = payload["boot_end_us"] || payload["exit_us"]
+        a[:phase]["vm_boot"] = (payload["t0_real"] - spawn_at) * 1000.0 if spawn_at && payload["t0_real"]
+        a[:phase]["boot"] = boot_us / 1000.0 if boot_us
+        a[:phase]["total"] = (a[:phase]["vm_boot"] || 0.0) + boot_us / 1000.0 if boot_us
+
+        main.each do |s|
+          self_ms = selfs[s] / 1000.0
+          dur_ms = s.dur_us / 1000.0
+          o = s.owner
+          case s.kind
+          when K_REQ, K_RR, K_LOAD
+            add_owner(a, o, self_ms, "require_ms")
+            f = a[:files][s.feature || s.name.to_s]
+            f["self_ms"] += self_ms
+            f["inclusive_ms"] += dur_ms
+            f["owner"] = o.name
+            f["category"] = o.category
+            f["count"] += 1
+          when K_ONLOAD
+            add_owner(a, o, self_ms, "on_load_ms")
+            e = a[:on_loads][[s.name, s.res.is_a?(String) ? s.res : nil]]
+            e["inclusive_ms"] += dur_ms
+            e["self_ms"] += self_ms
+            e["owner"] = o.name
+            e["category"] = o.category
+          when K_INIT
+            # initializer 本体の自己時間 (require や子に帰属できない分) は定義元 gem に付けず、init_body_ms として別掲する
+            ctx = s.res.is_a?(Array) ? s.res[0] : nil
+            e = a[:initializers][[s.name, ctx]]
+            e["inclusive_ms"] += dur_ms
+            e["init_body_ms"] += self_ms
+            a[:categories]["init_body"]["self_ms"] += self_ms
+            e["owner"] = o.name
+            # 時間は付けないが、initializer を定義していること (= Railtie/Engine) は記録する
+            g = a[:gems][o.name]
+            g["category"] = o.category
+            g["initializer_count"] += 1
+            e["category"] = o.category
+          when K_PHASE
+            key = s.name
+            a[:phase][key] = a[:phase][key].to_f + dur_ms if %w[bundler_require initialize].include?(key)
+          when K_EAGER
+            # eager_load_namespaces の span (meta = 定義位置) は自己時間を持ち主に付ける。Zeitwerk の span は従来どおり。
+            if s.res.is_a?(String)
+              add_owner(a, o, self_ms, "eager_ms")
+              e = a[:eager_namespaces][s.name]
+              e["inclusive_ms"] += dur_ms
+              e["self_ms"] += self_ms
+              e["owner"] = o.name
+              e["category"] = o.category
+            end
+            a[:phase]["eager_load"] = a[:phase]["eager_load"].to_f + dur_ms unless eager_ancestor?(s, pmap)
+          end
+        end
+        # 帰属されなかった時間 (run_load_hooks 自体、phase / eager_load span の自己時間、span の外) を別掲する
+        if boot_us
+          attributed = a[:categories].values.sum { |c| c["self_ms"] }
+          a[:categories]["unattributed"]["self_ms"] = [boot_us / 1000.0 - attributed, 0.0].max
+        end
+        a
+      end
+
+      private
+
+      def stat(values)
+        v = values.compact
+        return nil if v.empty?
+        s = v.sort
+        n = s.size
+        med = n.odd? ? s[n / 2] : (s[n / 2 - 1] + s[n / 2]) / 2.0
+        { "median" => r(med), "min" => r(s.first), "max" => r(s.last) }
+      end
+
+      def r(x) = x.is_a?(Float) ? x.round(3) : x
+
+      def phases(analyses)
+        keys = %w[vm_boot bundler_require initialize eager_load boot total]
+        keys.to_h { |k| [k, stat(analyses.map { |a| a[:phase][k] })] }
+      end
+
+      # runs 個の Hash (key => { metric => number, ... }) を key ごとに metric ごとの stat にする。
+      # 欠けた run は 0 として扱う。非数値の属性 (owner など) は最初に見つかった値を使う。
+      def merge_runs(list)
+        keys = list.flat_map(&:keys).uniq
+        keys.to_h do |k|
+          rows = list.map { |h| h[k] }
+          sample = rows.compact.first
+          out = {}
+          sample.each do |m, v|
+            out[m] = v.is_a?(Numeric) ? stat(rows.map { |row| row ? row[m] : 0 }) : v
+          end
+          [k, out]
+        end
+      end
+
+      def keyed_stats(list, order_by:)
+        merge_runs(list).sort_by { |_, v| -v[order_by]["median"] }.to_h
+      end
+
+      def gems(analyses)
+        merged = merge_runs(analyses.map { |a| a[:gems].to_h })
+        merged.sort_by { |k, v| [-v["self_ms"]["median"], k] }.map { |k, v| { "name" => k }.merge(v) }
+      end
+
+      def files(analyses)
+        merged = merge_runs(analyses.map { |a| a[:files].to_h })
+        merged.sort_by { |k, v| [-v["self_ms"]["median"], k] }.first(@top_files).map { |k, v| { "path" => k }.merge(v) }
+      end
+
+      def initializers(analyses)
+        merged = merge_runs(analyses.map { |a| a[:initializers].to_h })
+        merged.sort_by { |k, v| [-v["inclusive_ms"]["median"], k.to_s] }.first(@top_initializers).map do |(name, ctx), v|
+          { "name" => name, "context" => ctx }.merge(v)
+        end
+      end
+
+      # Advisor (heavy_app_initializer) 用。表示用の top-N 切り詰めをかけない app 側の inclusive 時間。
+      def app_initializer_times(analyses)
+        inits = merge_runs(analyses.map { |a| a[:initializers].to_h }).select { |_, v| v["category"] == "app" }
+        files = merge_runs(analyses.map { |a| a[:files].to_h }).select { |k, v| v["category"] == "app" && k.include?("/config/initializers/") }
+        {
+          "initializers" => inits.map { |(name, ctx), v| { "name" => name, "context" => ctx, "category" => "app", "inclusive_ms" => v["inclusive_ms"] } },
+          "files" => files.map { |k, v| { "path" => k, "category" => "app", "inclusive_ms" => v["inclusive_ms"] } }
+        }
+      end
+
+      def on_loads(analyses)
+        merged = merge_runs(analyses.map { |a| a[:on_loads].to_h })
+        merged.sort_by { |k, v| [-v["inclusive_ms"]["median"], k.to_s] }.first(@top_on_loads).map do |(name, loc), v|
+          { "name" => name, "source" => loc }.merge(v)
+        end
+      end
+
+      # config.eager_load_namespaces の eager_load! (TZInfo.eager_load! など)。件数は数十なので切り詰めない。
+      def eager_namespaces(analyses)
+        merged = merge_runs(analyses.map { |a| a[:eager_namespaces].to_h })
+        merged.sort_by { |k, v| [-v["inclusive_ms"]["median"], k.to_s] }.map { |name, v| { "name" => name }.merge(v) }
+      end
+
+      def add_owner(a, owner, self_ms, kind_key)
+        # app / stdlib / other も gems の表に並べる (ランキングで比較できるように)
+        g = a[:gems][owner.name]
+        g["category"] = owner.category
+        g["self_ms"] += self_ms
+        g[kind_key] += self_ms
+        a[:categories][owner.category]["self_ms"] += self_ms
+      end
+
+      # 入れ子の eager_load (eager_load_all が各 loader の eager_load を呼ぶ形) を二重に数えない
+      def eager_ancestor?(s, pmap)
+        while (s = pmap[s.parent])
+          return true if s.kind == K_EAGER
+        end
+        false
+      end
+
+      # --- 木の構築 -----------------------------------------------------------
+
+      def build_spans(payload)
+        w = payload["width"] || 8
+        ev = payload["events"] || []
+        exit_us = payload["exit_us"] || ev.each_slice(w).filter_map { |e| e[4] }.max || 0
+        spans = []
+        by_idx = {}
+        (0...(ev.size / w)).each do |i|
+          kind, name, par, t0, t1, res, tid, cpu = ev[i * w, w]
+          incomplete = t1.nil?
+          s = Span.new(i * w, kind, name, par, t0, t1 || [exit_us, t0].max, res, tid, cpu, [], incomplete, false, nil)
+          spans << s
+          by_idx[s.idx] = s
+        end
+        spans.each do |s|
+          p = by_idx[s.parent]
+          p.children << s if p
+        end
+        spans
+      end
+
+      # §3.4: 唯一の子が同じ feature の require 系なら 1 つにまとめる。まとめた件数を返す。
+      def normalize!(spans)
+        count = 0
+        spans.each do |s|
+          next if s.merged
+          while s.require_kind? && s.feature && s.children.size == 1
+            c = s.children.first
+            break unless c.require_kind? && c.feature == s.feature && c.tid == s.tid
+            c.merged = true
+            s.children = c.children
+            s.children.each { |g| g.parent = s.idx }
+            count += 1
+          end
+        end
+        # 外側から順に処理するので、親が先に処理される (EV は先行順)
+        count
+      end
+
+      # --- 帰属 ---------------------------------------------------------------
+
+      def owner_of(s, resolver)
+        case s.kind
+        when K_REQ, K_RR, K_LOAD
+          path = s.feature || (s.name.to_s.start_with?("/") ? s.name.to_s : nil)
+          path ? resolver.owner(path) : Owner.new("other", "other")
+        when K_ONLOAD
+          loc = s.res.is_a?(String) ? s.res.sub(/:\d+\z/, "") : nil
+          loc ? resolver.owner(loc) : Owner.new("other", "other")
+        when K_EAGER
+          s.res.is_a?(String) ? resolver.owner(s.res.sub(/:\d+\z/, "")) : Owner.new("other", "other")
+        when K_INIT
+          loc = s.res.is_a?(Array) && s.res[1].is_a?(String) ? s.res[1].sub(/:\d+\z/, "") : nil
+          loc ? resolver.owner(loc) : Owner.new("other", "other")
+        else
+          Owner.new("other", "other")
+        end
+      end
+
+      # specs / rails_root / libdir から、パスの持ち主を最長前方一致で引く。
+      class OwnerResolver
+        def initialize(payload)
+          @pwd = payload["pwd_realpath"]
+          @cache = {}
+          @real = {}
+          gem_prefixes = []
+          (payload["specs"] || {}).each do |name, (_ver, path, ext)|
+            [path, ext].compact.each { |pth| prefixes(pth).each { |pf| gem_prefixes << [pf, name] } }
+          end
+          @gems = gem_prefixes.uniq.sort_by { |pf, _| -pf.size }
+          root = payload["rails_root"] || @pwd
+          @app = root && prefixes(root)
+          # アプリ自身が gem (gemspec / path: "." / engine の dummy app) のとき、gem の prefix がアプリ root を含んでしまう。
+          # その場合は app/config/lib/db 配下を gem より先に app とみなす。
+          @app_dirs = nil
+          if @app && @gems.any? { |pf, _| @app.any? { |a| under?(a, pf) } }
+            @app_dirs = @app.flat_map { |a| %w[app config lib db].map { |d| File.join(a, d) } }
+          end
+          @stdlib = Array(payload["libdir"]).flat_map { |d| prefixes(d) }.uniq
+        end
+
+        def owner(path)
+          path = File.expand_path(path, @pwd || Dir.pwd) unless path.start_with?("/")
+          dir = File.dirname(path)
+          @cache[dir] ||= resolve_dir(dir)
+        end
+
+        private
+
+        def prefixes(path)
+          [path, realpath(path)].compact.uniq
+        end
+
+        def realpath(path)
+          @real[path] ||= begin
+            File.realpath(path)
+          rescue SystemCallError
+            path
+          end
+        end
+
+        def under?(dir, prefix) = dir == prefix || dir.start_with?(prefix.end_with?("/") ? prefix : "#{prefix}/")
+
+        def resolve_dir(dir)
+          dirs = [dir, realpath(dir)].uniq
+          return Owner.new("app", "app") if @app_dirs&.any? { |pf| dirs.any? { |d| under?(d, pf) } }
+          # 最長一致: gem の full_gem_path / extension_dir
+          hit = @gems.find { |pf, _| dirs.any? { |d| under?(d, pf) } }
+          return Owner.new("gem", hit[1]) if hit
+          return Owner.new("app", "app") if @app&.any? { |pf| dirs.any? { |d| under?(d, pf) } }
+          return Owner.new("stdlib", "stdlib") if @stdlib.any? { |pf| dirs.any? { |d| under?(d, pf) } }
+          Owner.new("other", "other")
+        end
+      end
+    end
+  end
+end