railbow 0.6.2 → 0.7.0

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: ps-123, 123, abc123, ab-123-456, feat/ps-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

data/lib/railbow/status/git_data.rb

@@ -1,19 +1,16 @@
 # frozen_string_literal: true
 
 require "date"
+require "time"
+require_relative "../clock"
 require_relative "../git_utils"
 require_relative "../multi_db"
 require_relative "../params"
 
 module Railbow
   module Status
-    # Every git lookup db:migrate:status makes about a migrations directory:
-    # who wrote each migration, when it landed on the mainline, which branch
-    # introduced it, and what is still uncommitted.
-    #
-    # One instance per migrations directory. Multi-database runs reuse the
-    # instance across databases that share a directory, which is what keeps
-    # `git log` from running once per database.
+    # Every git lookup db:migrate:status makes about one migrations directory:
+    # authors, landing dates, originating branches and uncommitted files.
     class GitData
       EMPTY_AUTHORS = {names: {}, emails: {}}.freeze
 
@@ -37,10 +34,8 @@ module Railbow
         load_diff(branch_mask, base_override) if diff_enabled && migrate_dir
       end
 
-      # Shares one instance per migrations directory across a multi-database
-      # run. Databases that share a directory (shards) or a run that renders
-      # several databases would otherwise repeat the same full-history
-      # `git log` once per database.
+      # One instance per migrations directory across a multi-database run, so
+      # the full-history `git log` does not repeat once per database.
       def self.for(migrate_dir:, **opts)
         cache = Railbow::MultiDb.current&.git_cache
         return new(migrate_dir: migrate_dir, **opts) unless cache
@@ -137,8 +132,8 @@ module Railbow
           line = line.strip
           if line.start_with?("COMMIT:")
             current_date = begin
-              Date.parse(line.sub("COMMIT:", ""))
-            rescue Date::Error
+              Railbow::Clock.in_zone(Time.iso8601(line.sub("COMMIT:", ""))).to_date
+            rescue ArgumentError
               nil
             end
           elsif !line.empty? && current_date
@@ -242,11 +237,9 @@ module Railbow
         branches_out.each_line.map(&:strip).reject(&:empty?)
       end
 
-      # Picks the branch that originally introduced the commit.
-      # 1. Drop child branches: if A is an ancestor of B, the commit came from A.
-      # 2. Among the rest, prefer the branch with the most commits after the
-      #    adding commit - it has been active longest since, so it is the
-      #    original rather than a newer fork.
+      # Picks the branch that introduced the commit: child branches drop out
+      # (if A is an ancestor of B, the commit came from A), then the branch
+      # with the most commits since wins, as the original rather than a fork.
       def pick_origin_branch(branches, commit)
         return branches.first if branches.size == 1
 

data/lib/railbow/status/help.rb

@@ -33,6 +33,12 @@ module Railbow
                                      short      - Jan 30 (column: Date)
                                      custom(…)  - user strftime, e.g. custom(%b %d, %Y)
 
+            RBW_TZ=<zone>            Timezone dates are shown in (default: local):
+                                     local      - this machine's timezone
+                                     utc        - UTC, the digits of the Migration ID
+                                     <name>     - any zone Rails knows, e.g.
+                                                  America/New_York
+
             RBW_VIEW=<options>       Display options (comma-separated):
                                      calendar   - show month/year separator lines + week ticks
                                      tables     - parse migration files, show Tables column