railbow 0.6.0 → 0.7.0

data/lib/railbow/notes_formatter.rb

@@ -2,6 +2,7 @@
 
 require "zlib"
 require "date"
+require_relative "clock"
 require_relative "git_utils"
 require_relative "formatters/base"
 require_relative "logo"
@@ -30,9 +31,18 @@ module Railbow
 
     PALETTE = Formatters::Base::TABLE_PALETTE
 
+    # git blame's author-mail for lines not committed yet
+    UNCOMMITTED_EMAIL = "not.committed.yet"
+
     def display(results, options = {})
       return super if Railbow.plain?
 
+      Railbow.guard(-> { super }) { railbow_display(results, options) }
+    end
+
+    private
+
+    def railbow_display(results, options = {})
       if Railbow::Params.help?
         print_help
         return
@@ -45,7 +55,6 @@ module Railbow
       since_date = Railbow::Params.parse_since(since_val, context: "annotations")
       git_needed = %w[all me].include?(author_mode) || since_date || sort_mode == "date"
 
-      # Build blame cache for all files if git features are needed
       blame_cache = {}
       if git_needed
         results.each_key do |source_file|
@@ -53,7 +62,7 @@ module Railbow
         end
       end
 
-      # Flatten annotations into a list for filtering/sorting
+      # Flattened so filtering and sorting can cross file boundaries
       entries = []
       results.each do |source_file, annotations|
         annotations.each do |annotation|
@@ -66,7 +75,6 @@ module Railbow
         end
       end
 
-      # Filter by SINCE
       skipped = 0
       if since_date
         before = entries.size
@@ -76,7 +84,7 @@ module Railbow
         skipped = before - entries.size
       end
 
-      # Sort by date (newest first) when requested
+      # Newest first; entries with no blame date sink to the end
       if sort_mode == "date"
         entries.sort_by! do |entry|
           d = entry.dig(:blame, :date)
@@ -84,21 +92,23 @@ module Railbow
         end
       end
 
-      # Determine "me" identity
       git_email = nil
       if author_mode == "me"
         git_email = current_git_email
       end
 
-      # Determine max location width for alignment when showing metadata
+      # Locations pad to one width so the author and date line up
       show_date = git_needed
       max_loc_width = 0
       author_colors = nil
       author_display = {}
       if author_mode == "all"
-        author_names = entries.filter_map { |e| e.dig(:blame, :author) }.uniq
+        author_names = entries.reject { |e| uncommitted?(e[:blame]) }
+          .filter_map { |e| e.dig(:blame, :author) }.uniq
         author_colors = ColorAssigner.new(author_names)
         author_display = Railbow::Params.format_authors(author_names)
+        # Uncommitted notes have no author; dashes fill the author column instead
+        no_author = "-" * (author_display.values.map(&:length).max || 4)
       end
       if show_date || author_mode == "all"
         entries.each do |entry|
@@ -107,11 +117,10 @@ module Railbow
         end
       end
 
-      # Group entries back by file for bar coloring
+      # A file with several notes gets its own bar color; a lone note's bar is dim
       file_counts = Hash.new(0)
       entries.each { |e| file_counts[e[:file]] += 1 }
 
-      # Display
       entries.each do |entry|
         source_file = entry[:file]
         annotation = entry[:annotation]
@@ -127,7 +136,6 @@ module Railbow
           DIM
         end
         colored_bar = "#{bar_color}#{BAR}#{RESET}"
-        # When highlighting "me", use bright white bar
         colored_bar = "#{WHITE}#{BAR}#{RESET}" if is_mine
 
         tag = annotation.tag
@@ -136,7 +144,6 @@ module Railbow
         colored_tag = "#{tag_color}#{BOLD}#{tag}#{RESET}"
         note = annotation.text.to_s.encode("UTF-8", invalid: :replace, undef: :replace)
 
-        # Build the file:line row with optional author+date
         loc_line = " #{colored_bar} #{location}"
 
         if author_mode == "all" && blame_info
@@ -144,7 +151,11 @@ module Railbow
           author_name = author_display[raw_author] || Railbow::Params.format_author(raw_author)
           blame_date = blame_info[:date] ? blame_info[:date].strftime("%Y-%m-%d") : ""
           padding = " " * [(max_loc_width - location.length + 2), 2].max
-          colored_author = "#{author_colors.color_for(raw_author)}#{author_name}#{RESET}"
+          colored_author = if uncommitted?(blame_info)
+            "#{DIM}#{no_author}#{RESET}"
+          else
+            "#{author_colors.color_for(raw_author)}#{author_name}#{RESET}"
+          end
           meta = "#{colored_author}  #{DIM}#{blame_date}#{RESET}"
           loc_line = " #{colored_bar} #{location}#{padding}#{meta}"
         elsif author_mode == "me" && is_mine && blame_info
@@ -164,7 +175,6 @@ module Railbow
         indent_width = 1 + 1 + 1 + 3 + tag.length + 1 # " " + BAR + " " + "   " + TAG + " "
         continuation_prefix = " #{colored_bar}   #{" " * (tag.length + 1)}"
 
-        # Apply "me" highlighting to note text
         if is_mine
           tag_str = "#{WHITE}#{tag}#{RESET} "
         end
@@ -198,13 +208,14 @@ module Railbow
       puts
     end
 
-    private
-
     def blame_file(path)
       return {} unless File.exist?(path)
 
-      output, status = Railbow::GitUtils.capture2("blame", "--porcelain", path)
-      return {} unless status.success?
+      # stderr is captured so "no such path in HEAD" never reaches the terminal
+      output, _err, status = Railbow::GitUtils.capture3("blame", "--porcelain", path)
+      # Untracked or ignored files (e.g. app/assets/builds) count as uncommitted,
+      # the way git blame dates uncommitted lines, so RBW_SINCE keeps them
+      return Hash.new(uncommitted_blame) unless status.success?
 
       result = {}
       current_line = nil
@@ -227,8 +238,8 @@ module Railbow
         elsif line.start_with?("author-time ")
           current_time = line.sub("author-time ", "").to_i
         elsif line.start_with?("\t") && current_line
-          # End of this blame entry — store it
-          date = current_time ? Time.at(current_time).to_date : nil
+          # The tab-prefixed source line closes a porcelain blame entry
+          date = current_time ? Railbow::Clock.in_zone(Time.at(current_time)).to_date : nil
           result[current_line] = {
             author: current_author,
             email: current_email,
@@ -240,6 +251,18 @@ module Railbow
       result
     end
 
+    def uncommitted_blame
+      {
+        author: "Not Committed Yet",
+        email: UNCOMMITTED_EMAIL,
+        date: Railbow::Clock.in_zone(Time.now).to_date
+      }.freeze
+    end
+
+    def uncommitted?(blame_info)
+      blame_info&.dig(:email) == UNCOMMITTED_EMAIL
+    end
+
     def current_git_email
       output, _status = Railbow::GitUtils.capture2("config", "user.email")
       output.strip.downcase

data/lib/railbow/params.rb

@@ -2,6 +2,7 @@
 
 require "date"
 require_relative "calendar"
+require_relative "clock"
 require_relative "config"
 require_relative "name_formatter"
 require_relative "name_collision_resolver"
@@ -10,10 +11,11 @@ module Railbow
   module Params
     module_function
 
-    # Parse compound ENV value: "author:me,diff,base:develop"
-    # → { "author" => "me", "diff" => true, "base" => "develop" }
-    # Repeated keys collect into arrays: "hide:date,hide:author"
-    # → { "hide" => ["date", "author"] }
+    # Parse a compound ENV value; repeated keys collect into arrays.
+    #   parse_compound("author:me,diff,base:develop")
+    #   # => { "author" => "me", "diff" => true, "base" => "develop" }
+    #   parse_compound("hide:date,hide:author")
+    #   # => { "hide" => ["date", "author"] }
     def parse_compound(value)
       return {} if value.nil? || value.strip.empty?
 
@@ -54,11 +56,12 @@ module Railbow
       amount = match[1].to_i
       unit = match[2].downcase
 
+      today = Clock.today
       case unit
-      when "d" then Date.today - amount
-      when "w" then Date.today - (amount * 7)
-      when "mo", "m" then Date.today.prev_month(amount)
-      when "y" then Date.today.prev_year(amount)
+      when "d" then today - amount
+      when "w" then today - (amount * 7)
+      when "mo", "m" then today.prev_month(amount)
+      when "y" then today.prev_year(amount)
       end
     end
 
@@ -80,12 +83,9 @@ module Railbow
       (ENV["RBW_SINCE"] || Config.load["since"] || "all").strip.downcase
     end
 
-    # Floor on how many migrations survive the SINCE window. The window is a
-    # soft limit: when it leaves fewer rows than this, the oldest ones are
-    # pulled back in until the count is met. 0 disables the floor.
-    #
-    # Deliberately a knob of its own rather than a token inside RBW_SINCE, so
-    # an ad-hoc `RBW_SINCE=2mo` keeps the floor instead of silently dropping it.
+    # Floor on how many migrations survive the SINCE window: when it leaves
+    # fewer rows, the oldest are pulled back in. 0 disables the floor. A knob of
+    # its own, not a RBW_SINCE token, so an ad-hoc `RBW_SINCE=2mo` keeps it.
     def since_min
       value = ENV["RBW_SINCE_MIN"] || Config.load["since_min"] || 0
       [value.to_i, 0].max
@@ -161,15 +161,14 @@ module Railbow
       ENV["RBW_AUTHOR_FORMAT"] || Config.load["author_format"] || "short"
     end
 
-    # Format an author name using NameFormatter.
-    # Accepts preset names ("initials", "first_name", etc.) or
-    # custom patterns ("FF L", "FFFF L.", "LLLL, FFFF").
+    # author_format is a preset ("initials", "first_name", ...) or a custom
+    # pattern ("FF L", "FFFF L.", "LLLL, FFFF").
     def format_author(name)
       NameFormatter.format(name, author_format)
     end
 
-    # Format a batch of author names with collision resolution.
-    # Returns Hash{String => String} mapping raw names to disambiguated formatted names.
+    # Formats a batch of names so two different authors never render the same.
+    # Returns Hash{String => String} of raw name to formatted name.
     def format_authors(names)
       NameCollisionResolver.resolve(names, author_format)
     end
@@ -188,12 +187,11 @@ module Railbow
       val.is_a?(String) ? val : ""
     end
 
-    # Built-in regex for extracting ticket/task identifiers from branch names.
-    # Matches patterns like: ws-123, 123, abc123, ab-123-456, feat/ws-1234, feat/123-some-feature
+    # Ticket ids in branch names: ps-123, 123, abc123, ab-123-456, feat/ps-1234,
+    # feat/123-some-feature.
     TICKET_RE = /(?:^|\/)([a-z]{1,5}-?\d+(?:-\d+)*|\d+(?:-\d+)*)/i
 
-    # Extract a ticket identifier from a branch name.
-    # Returns the matched identifier or the original branch name if no match.
+    # The branch's ticket id, or the whole branch name when it has none.
     def extract_branch_ticket(branch)
       m = branch.match(TICKET_RE)
       m ? m[1] : branch
@@ -208,6 +206,15 @@ module Railbow
       val.to_s.strip
     end
 
+    # --- RBW_TZ ---
+
+    def tz
+      val = ENV["RBW_TZ"] || Config.load["tz"]
+      return "local" if val.nil? || val.to_s.strip.empty?
+
+      val.to_s.strip
+    end
+
     # --- Compound: RBW_VIEW ---
 
     def view
@@ -244,10 +251,9 @@ module Railbow
       db["full"] == true
     end
 
-    # Expand only the first database, summarizing the rest in a line each - but
-    # never at the cost of hiding work: a database holding pending migrations
-    # is always drawn in full, since that is the one thing you may need to act
-    # on. RBW_DB=full overrides it, and it does not apply to inline runs.
+    # Expand only the first database, summarizing the rest in a line each. A
+    # database with pending migrations is always drawn in full, since that is
+    # what you may need to act on. RBW_DB=full overrides it; inline ignores it.
     def db_focus?
       db["focus"] == true
     end

data/lib/railbow/railtie.rb

@@ -4,37 +4,39 @@ require "rails/railtie"
 
 module Railbow
   class Railtie < Rails::Railtie
-    # Initialize after ActiveRecord is loaded
+    # on_load, so booting the app does not force ActiveRecord to load early.
     initializer "railbow.enhance_migrations" do
       ActiveSupport.on_load(:active_record) do
         require_relative "migration_formatter"
 
-        # Prepend our formatter module to ActiveRecord::Migration
         ActiveRecord::Migration.prepend(Railbow::MigrationFormatter)
       end
     end
 
-    # Enhance routes output with colors
     initializer "railbow.enhance_routes", after: :load_config_initializers do
       require "action_dispatch/routing/inspector"
       require_relative "routes_formatter"
       ActionDispatch::Routing::ConsoleFormatter::Sheet.prepend(Railbow::RoutesFormatter)
     end
 
-    # Enhance `rails about` output
     initializer "railbow.enhance_about", after: :load_config_initializers do
       require_relative "about_formatter"
       Rails::Info.singleton_class.prepend(Railbow::AboutFormatter)
     end
 
-    # Enhance `rails notes` output
     initializer "railbow.enhance_notes", after: :load_config_initializers do
       require "rails/source_annotation_extractor"
       require_relative "notes_formatter"
       Rails::SourceAnnotationExtractor.prepend(Railbow::NotesFormatter)
     end
 
-    # Load custom Rake tasks
+    # Since Rails 8.0 `rails stats` is a Rails command that boots the app but
+    # never loads rake tasks, so the .rake file alone cannot install this.
+    initializer "railbow.enhance_stats", after: :load_config_initializers do
+      require_relative "stats_formatter"
+      Railbow::StatsFormatter.install!
+    end
+
     rake_tasks do
       load "railbow/tasks/migrate_status.rake"
       load "railbow/tasks/stats.rake"

data/lib/railbow/routes_formatter.rb

@@ -62,12 +62,22 @@ module Railbow
         return
       end
 
-      strip_format = Railbow::Params.compact_strip_format?
-      prepared = routes.map { |r| prepare_route(r, strip_format) }
-      prepared = filter_by_verb(prepared)
+      # A failure drops whatever this section already buffered, then renders
+      # it the Rails way, header included since railbow normally hides it.
+      mark = @buffer.size
+      plain = lambda do
+        @buffer.slice!(mark..)
+        header(routes)
+        super
+      end
+      Railbow.guard(plain) do
+        strip_format = Railbow::Params.compact_strip_format?
+        prepared = routes.map { |r| prepare_route(r, strip_format) }
+        prepared = filter_by_verb(prepared)
 
-      groups = group_routes(prepared)
-      groups.each { |label, group| render_group(label, group) }
+        groups = group_routes(prepared)
+        groups.each { |label, group| render_group(label, group) }
+      end
     end
 
     private
@@ -97,7 +107,9 @@ module Railbow
         Table::Column.new(label: "Verb", sticky: true),
         Table::Column.new(label: "URI Pattern", sticky: true),
         Table::Column.new(label: "Controller#Action"),
-        Table::Column.new(label: "Prefix")
+        # The route name is the least of the four, so a group too wide for the
+        # terminal gives it up rather than wrapping past the edge.
+        Table::Column.new(label: "Prefix", droppable: 1)
       ]
 
       rows = routes.map { |r|

data/lib/railbow/stats_formatter.rb

@@ -6,94 +6,164 @@ require_relative "table"
 
 module Railbow
   module StatsFormatter
+    RESET = Formatters::Base::RESET
+    DIM = Formatters::Base::DIM
+    CODE_COLOR = "\e[38;5;76m"  # green
+    TEST_COLOR = "\e[38;5;39m"  # cyan
+
+    BAR_WIDTH = 16
+    BAR_EIGHTHS = ["", "▏", "▎", "▍", "▌", "▋", "▊", "▉"].freeze
+    FULL_BLOCK = "█"
+
+    # Rails 8 names the class Rails::CodeStatistics, Rails 7.2 a top-level
+    # CodeStatistics; both live in "rails/code_statistics". Prepending twice is
+    # a no-op, so every entry point may call this.
+    def self.install!
+      require "rails/code_statistics"
+      klass = defined?(Rails::CodeStatistics) ? Rails::CodeStatistics : ::CodeStatistics
+      klass.prepend(self)
+    rescue LoadError
+      # railties without code statistics: nothing to decorate
+    end
+
+    # Stock Rails prints the table from to_s and returns nil, and both the
+    # stats command and the rake task rely on that, so this prints too.
     def to_s
       return super if Railbow.plain?
 
-      formatter = Formatters::Base.new
+      Railbow.guard(-> { super }) do
+        puts railbow_render
+        nil
+      end
+    end
+
+    private
+
+    def railbow_render
+      f = Formatters::Base.new
+      tests = railbow_test_types
+      names = @pairs.map(&:first)
+      code_names = names.reject { |n| tests.include?(n) }
+      test_names = names.select { |n| tests.include?(n) }
+
+      total = railbow_sum(@statistics.values)
+      max_loc = @statistics.values.map(&:code_lines).max.to_i
 
-      columns = [
+      rows = []
+      separators = {}
+      [["Code", code_names, CODE_COLOR, false], ["Tests", test_names, TEST_COLOR, true]].each do |label, group, color, test|
+        next if group.empty?
+
+        # A heading row rather than a renderer separator, which would put the
+        # label past the first column.
+        rows << [Table::Themes::WALLS.format_separator.call(label), *Array.new(7, "")]
+        group.each do |name|
+          rows << railbow_row(f, name, @statistics[name], total, max_loc, color, test: test)
+        end
+      end
+      separators[rows.size] = "" if rows.size > 1
+      rows << railbow_total_row(f, total)
+
+      renderer = Table::Renderer.new(
+        columns: railbow_columns,
+        theme: Table::Themes::WALLS,
+        compact: Railbow::Params.compact_options,
+        aliases: Railbow::Config.table_aliases
+      )
+
+      out = +"\n"
+      out << renderer.render(rows, separators: separators)
+      out << "\n\n"
+      out << railbow_summary(f, code_names, test_names)
+      out << "\n"
+      out
+    end
+
+    def railbow_columns
+      [
         Table::Column.new(label: "Name", sticky: true),
         Table::Column.new(label: "Lines", align: :right),
         Table::Column.new(label: "LOC", align: :right),
         Table::Column.new(label: "Classes", align: :right),
         Table::Column.new(label: "Methods", align: :right),
         Table::Column.new(label: "M/C", align: :right),
-        Table::Column.new(label: "LOC/M", align: :right)
+        Table::Column.new(label: "LOC/M", align: :right),
+        Table::Column.new(label: "Share of LOC")
       ]
+    end
 
-      rows = []
-      total_lines = 0
-      total_loc = 0
-      total_classes = 0
-      total_methods = 0
-      code_loc = 0
-      test_loc = 0
-
-      @pairs.each do |pair|
-        name, stats = pair
-        lines = stats.lines
-        loc = stats.code_lines
-        classes = stats.classes
-        methods = stats.methods
-        mc = (classes > 0) ? (methods.to_f / classes).round(0).to_i : 0
-        locm = (methods > 0) ? ((loc.to_f / methods) - 2).round(0).to_i : 0
-
-        total_lines += lines
-        total_loc += loc
-        total_classes += classes
-        total_methods += methods
-
-        if stats.test_file?
-          test_loc += loc
-        else
-          code_loc += loc
-        end
+    # M/C and LOC/M say little about test code, where most blocks are not
+    # methods, so on test rows they step back.
+    def railbow_row(f, name, stats, total, max_loc, color, test:)
+      ratios = railbow_ratios(stats).map { |v| test ? f.dim(railbow_num(v)) : railbow_count(f, v) }
+      [
+        name,
+        railbow_count(f, stats.lines),
+        railbow_count(f, stats.code_lines),
+        railbow_count(f, stats.classes),
+        railbow_count(f, stats.methods),
+        *ratios,
+        railbow_share(f, stats.code_lines, total.code_lines, max_loc, color)
+      ]
+    end
 
-        rows << [
-          name,
-          lines.to_s,
-          loc.to_s,
-          classes.to_s,
-          methods.to_s,
-          mc.to_s,
-          locm.to_s
-        ]
-      end
+    def railbow_total_row(f, total)
+      cells = [total.lines, total.code_lines, total.classes, total.methods, *railbow_ratios(total)]
+      [f.bold("Total"), *cells.map { |v| f.bold(railbow_num(v)) }, ""]
+    end
 
-      # Total row
-      total_mc = (total_classes > 0) ? (total_methods.to_f / total_classes).round(0).to_i : 0
-      total_locm = (total_methods > 0) ? ((total_loc.to_f / total_methods) - 2).round(0).to_i : 0
-
-      rows << [
-        formatter.bold("Total"),
-        formatter.bold(total_lines.to_s),
-        formatter.bold(total_loc.to_s),
-        formatter.bold(total_classes.to_s),
-        formatter.bold(total_methods.to_s),
-        formatter.bold(total_mc.to_s),
-        formatter.bold(total_locm.to_s)
-      ]
+    # Integer math, as stock Rails does it, so the numbers match its table.
+    def railbow_ratios(stats)
+      m_over_c = stats.classes.zero? ? 0 : stats.methods / stats.classes
+      loc_over_m = stats.methods.zero? ? 0 : (stats.code_lines / stats.methods) - 2
+      [m_over_c, loc_over_m]
+    end
 
-      renderer = Table::Renderer.new(
-        columns: columns,
-        theme: Table::Themes::WALLS,
-        compact: Railbow::Params.compact_options,
-        aliases: Railbow::Config.table_aliases
-      )
+    # The bar is scaled to the biggest row so small directories stay visible;
+    # the percentage is of the whole codebase.
+    def railbow_share(f, loc, total_loc, max_loc, color)
+      return f.dim("-") if loc.zero? || total_loc.zero?
+
+      eighths = (BAR_WIDTH * 8 * loc.fdiv(max_loc)).round.clamp(1, BAR_WIDTH * 8)
+      bar = (FULL_BLOCK * (eighths / 8)) + BAR_EIGHTHS[eighths % 8]
+      share = 100.0 * loc / total_loc
+      pct = (share < 0.1) ? "<0.1%" : format("%.1f%%", share)
+      "#{color}#{bar.ljust(BAR_WIDTH)}#{RESET} #{f.dim(pct.rjust(5))}"
+    end
+
+    def railbow_summary(f, code_names, test_names)
+      code = code_names.sum { |n| @statistics[n].code_lines }
+      test = test_names.sum { |n| @statistics[n].code_lines }
 
-      output = +"\n"
-      output << renderer.render(rows)
-      output << "\n"
+      parts = ["#{CODE_COLOR}Code#{RESET} #{f.bold(railbow_num(code))} LOC"]
+      parts << "#{TEST_COLOR}Tests#{RESET} #{f.bold(railbow_num(test))} LOC"
+      parts << "Code to Test Ratio #{f.bold(format("1:%.1f", test.fdiv(code)))}" if code.positive?
+      "  #{parts.join(f.dim("   ·   "))}\n"
+    end
 
-      # Code/test ratio
-      if code_loc > 0 && test_loc > 0
-        ratio = (test_loc.to_f / code_loc).round(1)
-        output << "\n  #{formatter.bold("Code LOC:")} #{code_loc}   " \
-                  "#{formatter.bold("Test LOC:")} #{test_loc}   " \
-                  "#{formatter.bold("Code to Test Ratio:")} 1:#{ratio}\n"
+    def railbow_sum(calculators)
+      total = Struct.new(:lines, :code_lines, :classes, :methods).new(0, 0, 0, 0)
+      calculators.each do |s|
+        total.lines += s.lines
+        total.code_lines += s.code_lines
+        total.classes += s.classes
+        total.methods += s.methods
       end
+      total
+    end
+
+    # Rails 8 keeps the list in a class attribute that register_directory
+    # extends; Rails 7.2 in a constant that rspec-rails appends to.
+    def railbow_test_types
+      respond_to?(:test_types, true) ? test_types : self.class::TEST_TYPES
+    end
+
+    def railbow_count(f, value)
+      value.zero? ? f.dim("0") : railbow_num(value)
+    end
 
-      output
+    def railbow_num(value)
+      value.to_s.reverse.scan(/\d{1,3}/).join(",").reverse.then { |s| value.negative? ? "-#{s}" : s }
     end
   end
 end

data/lib/railbow/status/ghosts.rb

@@ -46,8 +46,8 @@ module Railbow
 
         rows = {}
         versions.each do |v|
-          # Absent from detect = deliberately suppressed (dismissed, or superseded
-          # with hide_superseded on) - render as plain NO FILE, do not re-recover.
+          # Absent from detect means suppressed (dismissed, or superseded with
+          # hide_superseded on): render as plain NO FILE, do not re-recover.
           next unless (orphan = orphans[v])
 
           row = if orphan.filename && !orphan.filename.empty?
@@ -73,9 +73,9 @@ module Railbow
         )
       end
 
-      # Detect reads stored snapshots only. A version it lists without a filename
-      # has no snapshot yet, so fall back to live git/worktree recovery - that
-      # keeps fresh clones working with zero setup.
+      # Detect reads stored snapshots only, so a version listed without a
+      # filename falls back to live git/worktree recovery. That keeps fresh
+      # clones working with zero setup.
       def from_live_recovery(version, with_content)
         snapshot = begin
           Mighost::API.find_or_recover_snapshot(version)
@@ -131,7 +131,6 @@ module Railbow
         end
       end
 
-      # The name a ghost row displays, derived from its recovered filename.
       def display_name(ghost)
         ghost.filename
           .sub(/\A\d+_/, "")      # strip version prefix