railbow 0.6.0 → 0.7.0

data/lib/railbow/formatters/base.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "zlib"
+require_relative "../clock"
 require_relative "../text_utils"
 
 module Railbow
@@ -34,6 +35,9 @@ module Railbow
 
       BRIGHT_WHITE = "\e[1;97m"
 
+      # Narrowest name a tagged cell will accept before the tags are dropped.
+      NAME_TAGS_FLOOR = 12
+
       def dim(str) = "#{DIM}#{str}#{RESET}"
       def green(str) = "#{GREEN}#{str}#{RESET}"
       def yellow(str) = "#{YELLOW}#{str}#{RESET}"
@@ -66,23 +70,20 @@ module Railbow
         table_names.map { |t| table_tag(t) }.join(" ")
       end
 
-      # Re-fits a pre-formatted table_tags string within max_width,
-      # showing full table names and "+N" for overflow.
-      # Accepts the full formatted string (with ANSI) and splits it into segments.
+      # Re-fits a formatted table_tags string within max_width: as many whole
+      # tags as fit plus "+N" for the rest, then one truncated tag, then "+N".
       def table_tags_fitted(formatted_str, max_width)
         return formatted_str if formatted_str.nil? || formatted_str.empty?
 
-        # Split into individual tag segments: each is "\e[38;5;NNNm● name\e[0m"
+        # Each tag is "\e[38;5;NNNm● name\e[0m"
         segments = formatted_str.scan(/\e\[38;5;\d+m● [^\e]+\e\[0m/)
         return formatted_str if segments.empty?
 
         total = segments.size
         plain_segments = segments.map { |s| strip_ansi(s) }
 
-        # Try fitting all tags
         return formatted_str if display_width(plain_segments.join(" ")) <= max_width
 
-        # Try fitting progressively fewer tags with +N suffix
         (total - 1).downto(1) do |count|
           remaining = total - count
           suffix = " +#{remaining}"
@@ -92,17 +93,13 @@ module Railbow
           end
         end
 
-        # Try fitting a truncated first table name + overflow.
-        # Need at least 7 chars: "● t… +N" (dot + color prefix use no visible width beyond the dot)
+        # A truncated first tag needs 7 columns at least: "● t… +N"
         if max_width >= 7
           suffix = (total > 1) ? " +#{total - 1}" : ""
-          # Available width for "● name…" part
           avail = max_width - display_width(suffix)
-          # "● " prefix = 2 chars visible, plus at least 1 char of name + ellipsis (1 char)
           if avail >= 4 # "● " (2) + at least 1 char + "…" (1)
             first_plain = plain_segments[0] # e.g. "● some_table"
             name_part = first_plain.sub(/^● /, "")
-            # Truncate name to fit: avail - 2 ("● ") - 1 ("…") = chars for name
             name_max = avail - 2 - 1
             truncated_name = name_part[0, name_max]
             color_match = segments[0].match(/\e\[38;5;\d+m/)
@@ -111,10 +108,33 @@ module Railbow
           end
         end
 
-        # Absolute fallback: just +N
         "+#{total}"
       end
 
+      # Re-fits a Migration Name cell whose tags (branch, landed) sit flush
+      # right. Cutting from the right would eat the tags and leave a bare
+      # ellipsis, so the name gives up the space instead. Below NAME_TAGS_FLOOR
+      # the tags go: the name is what the row is about.
+      def name_with_tags_fitted(cell, max_width)
+        str = cell.to_s
+        return truncate_ansi(str, max_width) if display_width(strip_ansi(str)) <= max_width
+
+        split = str.rindex(/\s{2,}\e\[/)
+        return truncate_ansi(str, max_width) unless split
+
+        # rindex stops at the last two spaces of the padding run, so the rest of
+        # it still hangs off the name and would be truncated in place of it.
+        name = str[0...split].rstrip
+        tags = str[split..].lstrip
+        tags_width = display_width(strip_ansi(tags))
+        name_room = max_width - tags_width - 2
+        return truncate_ansi(name, max_width) if name_room < NAME_TAGS_FLOOR
+
+        name = truncate_ansi(name, name_room)
+        padding = max_width - display_width(strip_ansi(name)) - tags_width
+        "#{name}#{" " * [padding, 2].max}#{tags}"
+      end
+
       def format_timing(seconds)
         milliseconds = (seconds * 1000).round(1)
 
@@ -141,16 +161,8 @@ module Railbow
 
       def format_date(timestamp, mode = "full")
         ts = timestamp.to_s
-        return ts if ts.length != 14
-
-        time = begin
-          Time.new(
-            ts[0..3].to_i, ts[4..5].to_i, ts[6..7].to_i,
-            ts[8..9].to_i, ts[10..11].to_i, ts[12..13].to_i
-          )
-        rescue ArgumentError
-          return ts
-        end
+        time = Railbow::Clock.from_version(ts)
+        return ts unless time
 
         case mode
         when "full"
@@ -166,8 +178,6 @@ module Railbow
         end
       end
 
-      private
-
       def format_relative_time_from(time)
         diff = Time.now - time
         return "just now" if diff < 0
@@ -188,8 +198,6 @@ module Railbow
         else "~#{years}y ago"
         end
       end
-
-      public
     end
   end
 end

data/lib/railbow/init.rb

@@ -20,7 +20,7 @@ module Railbow
       # Every key can also be overridden via RBW_* environment variables.
 
       # Time window for migrations to display (e.g. 30d, 2mo, 1y, all)
-      since: "70d"
+      since: "90d"
 
       # Never show fewer than this many migrations, however old they are.
       # The window above is a soft limit: a database with five migrations shows
@@ -37,7 +37,7 @@ module Railbow
       #   diff         - tag migrations by git origin branch
       #   base:<branch> - base branch for diff (default: auto-detected)
       #   mask:auto    - auto-extract ticket id from branch name
-      #   mask:<re>    - custom regex to extract branch label, e.g. mask:(WS-[^/]+)/
+      #   mask:<re>    - custom regex to extract branch label, e.g. mask:(PS-[^/]+)/
       git: "author:all,diff,mask:auto"
 
       # Author display format - preset or custom pattern (FF L, FFF LL, etc.):
@@ -60,6 +60,10 @@ module Railbow
       # Date format: full, rel, short, or custom(%b %d, %Y)
       # date: "full"
 
+      # Timezone dates are shown in: local (this machine), utc, or any zone
+      # Rails knows, e.g. America/New_York or "Eastern Time (US & Canada)"
+      # tz: "local"
+
       # Multi-database runs (comma-separated). Leave empty ("") to expand every
       # database into its own section, in database.yml order; a database with
       # nothing in the time window collapses to a one-line summary either way.

data/lib/railbow/migration_formatter.rb

@@ -10,30 +10,12 @@ module Railbow
     def announce(message)
       return super if Railbow.plain?
 
-      f = FORMATTER
-      migration_name = self.class.name&.demodulize || "Migration"
-
-      line = case message
-      when /migrating/i
-        f.cyan("#{f.emoji(:migrating)} #{migration_name}: migrating...")
-      when /migrated\s*\((\d+\.\d+)s\)/i
-        raw_seconds = Regexp.last_match(1).to_f
-        formatted = f.format_timing(raw_seconds)
-        f.green("#{f.emoji(:migrated)} #{migration_name}: migrated") + " (#{formatted} total)"
-      when /reverting/i
-        f.yellow("#{f.emoji(:reverting)} #{migration_name}: reverting...")
-      when /reverted\s*\((\d+\.\d+)s\)/i
-        raw_seconds = Regexp.last_match(1).to_f
-        formatted = f.format_timing(raw_seconds)
-        f.green("#{f.emoji(:reverted)} #{migration_name}: reverted") + " (#{formatted} total)"
-      else
-        "#{migration_name}: #{message}"
-      end
-
-      write ""
-      write line
+      Railbow.guard(-> { super }) { railbow_announce(message) }
     end
 
+    # The yield runs the migration itself, so it stays outside the guard: a
+    # failing migration must raise as usual, and a formatting error must not
+    # re-run it through super. The fallback prints what Rails would have.
     def say_with_time(message)
       return super { yield } if Railbow.plain?
 
@@ -41,9 +23,16 @@ module Railbow
       result = nil
       time = Benchmark.measure { result = yield }
 
-      timing = f.format_timing(time.real)
-      write "  #{f.green(f.emoji(:check))} #{message} → #{timing}"
-      say("#{result} rows", :subitem) if result.is_a?(Integer)
+      plain = lambda do
+        say(message)
+        say("%.4fs" % time.real, :subitem)
+        say("#{result} rows", :subitem) if result.is_a?(Integer)
+      end
+      Railbow.guard(plain) do
+        timing = f.format_timing(time.real)
+        write "  #{f.green(f.emoji(:check))} #{message} → #{timing}"
+        say("#{result} rows", :subitem) if result.is_a?(Integer)
+      end
 
       result
     end
@@ -60,5 +49,32 @@ module Railbow
 
       puts text
     end
+
+    private
+
+    def railbow_announce(message)
+      f = FORMATTER
+      migration_name = self.class.name&.demodulize || "Migration"
+
+      line = case message
+      when /migrating/i
+        f.cyan("#{f.emoji(:migrating)} #{migration_name}: migrating...")
+      when /migrated\s*\((\d+\.\d+)s\)/i
+        raw_seconds = Regexp.last_match(1).to_f
+        formatted = f.format_timing(raw_seconds)
+        f.green("#{f.emoji(:migrated)} #{migration_name}: migrated") + " (#{formatted} total)"
+      when /reverting/i
+        f.yellow("#{f.emoji(:reverting)} #{migration_name}: reverting...")
+      when /reverted\s*\((\d+\.\d+)s\)/i
+        raw_seconds = Regexp.last_match(1).to_f
+        formatted = f.format_timing(raw_seconds)
+        f.green("#{f.emoji(:reverted)} #{migration_name}: reverted") + " (#{formatted} total)"
+      else
+        "#{migration_name}: #{message}"
+      end
+
+      write ""
+      write line
+    end
   end
 end

data/lib/railbow/migration_parser.rb

@@ -4,7 +4,6 @@ require "active_support/inflector"
 
 module Railbow
   class MigrationParser
-    # Methods that take a single table name as the first argument
     SINGLE_TABLE_METHODS = %w[
       create_table drop_table change_table
       add_column remove_column rename_column change_column
@@ -15,7 +14,6 @@ module Railbow
       add_timestamps remove_timestamps
     ].freeze
 
-    # Methods that take two table names as arguments
     DUAL_TABLE_METHODS = %w[
       add_foreign_key remove_foreign_key
     ].freeze
@@ -25,7 +23,6 @@ module Railbow
     SINGLE_TABLE_PATTERN = /\b(?:#{(SINGLE_TABLE_METHODS + DUAL_TABLE_METHODS).join("|")})\s+[:"](\w+)/
     DUAL_TABLE_PATTERN = /\b(?:#{DUAL_TABLE_METHODS.join("|")})\s+[:"](\w+)["\s,]+[:"](\w+)/
 
-    # SQL keywords followed by a table name
     SQL_TABLE_PATTERNS = [
       /\bUPDATE\s+["']?(\w+)["']?/i,
       /\bINSERT\s+INTO\s+["']?(\w+)["']?/i,
@@ -36,21 +33,19 @@ module Railbow
       /\bCREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?["']?(\w+)["']?/i
     ].freeze
 
-    # Helper/DSL calls that name their target table via a keyword argument, e.g.
-    # `convert_to_monthly_partitions(table: :apples)` or
-    # `remove_foreign_key :accounts, to_table: :owners`. Catches project-level
-    # migration helpers regardless of the method name. Bare `from:`/`to:` are
-    # deliberately not matched — `change_column_default :users, :status,
+    # A table named by keyword argument, which catches project-level helpers
+    # such as `convert_to_monthly_partitions(table: :apples)` whatever their
+    # name. Not bare `from:`/`to:`: `change_column_default :users, :status,
     # from: nil, to: "active"` would yield phantom tables.
     KEYWORD_TABLE_PATTERN = /\b(?:table|to_table|from_table):\s*[:"']?(\w+)/
 
     # Ruby `#` comments up to end of line, but not `#{}` interpolation.
     COMMENT_PATTERN = /#(?!\{).*/
 
-    # AR class-level query/mutation methods that strongly signal a constant is a model.
-    # Kept narrow on purpose — methods like `find`, `all`, `first`, `count`, `create`,
-    # `new`, `transaction`, `order`, `includes` collide with stdlib/non-model constants
-    # (e.g. Time.new, File.find, Array#first) and would produce false positives.
+    # AR class methods that strongly signal a constant is a model. Kept narrow:
+    # `find`, `all`, `first`, `count`, `create`, `new`, `transaction`, `order`,
+    # `includes` also exist on non-model constants (Time.new, File.find) and
+    # would produce false positives.
     MODEL_AR_METHODS = %w[
       find_each find_in_batches
       find_by find_by!
@@ -74,9 +69,8 @@ module Railbow
     def self.extract_tables_from_content(content)
       return [] if content.nil? || content.empty?
 
-      # Comments would otherwise produce phantom tables — an explanatory
-      # "# ALTER TABLE foo ..." or a commented-out create_table reads exactly
-      # like the real thing to the patterns below.
+      # An explanatory "# ALTER TABLE foo ..." or a commented-out create_table
+      # reads exactly like the real thing to the patterns below.
       content = content.gsub(COMMENT_PATTERN, "")
 
       tables = []
@@ -89,10 +83,9 @@ module Railbow
       content.scan(KEYWORD_TABLE_PATTERN) { |match| tables << match[0] }
       tables.uniq!
 
-      # Model-based detection is heuristic (a constant that happens to respond
-      # to one of these methods isn't necessarily an AR model). Only use it to
-      # supplement sparse DDL/SQL findings — skip once we already know of ≥2
-      # tables, and cap the final total at 2.
+      # Model references are a guess (a constant answering these methods need
+      # not be a model), so they only fill in when DDL and SQL found fewer
+      # than 2 tables, and never take the total past 2.
       if tables.size < 2
         content.scan(MODEL_REFERENCE_PATTERN) do |match|
           break if tables.size >= 2

data/lib/railbow/multi_db.rb

@@ -51,10 +51,24 @@ module Railbow
       def flush
         return if empty?
 
-        Railbow::Status::Printer.new(@sections, skipped: @skipped).print
+        if Railbow.plain?
+          print_fallback
+        else
+          Railbow.guard(-> { print_fallback }) do
+            Railbow::Status::Printer.new(@sections, skipped: @skipped).print
+          end
+        end
         @sections = []
         @skipped = []
       end
+
+      private
+
+      # The stock Rails tables captured per database while their pools were
+      # still open; see MigrateStatusFormatter#migrate_status.
+      def print_fallback
+        @sections.each { |section| $stdout.write(section.fallback_output.to_s) }
+      end
     end
 
     module_function

data/lib/railbow/name_collision_resolver.rb

@@ -3,13 +3,9 @@
 require_relative "name_formatter"
 
 module Railbow
-  # Detects and resolves collisions when multiple different names produce the
-  # same formatted output.  Works by progressively expanding pattern tokens
-  # (F → FF → FFF → FFFF, then L) until every distinct raw name maps to a
-  # unique formatted string.
-  #
-  # Names that share the same first+last name but differ only in middle name
-  # are treated as the same person and merged before collision detection.
+  # Makes distinct names format distinctly by widening pattern tokens (F to
+  # FFFF, then L) until no two collide. Names differing only in the middle
+  # name count as one person and share an output.
   #
   #   NameCollisionResolver.resolve(["John Doe", "Jane Doe"], "F L")
   #   # => {"John Doe" => "Jo D", "Jane Doe" => "Ja D"}
@@ -20,19 +16,16 @@ module Railbow
 
     # @param names [Array<String, nil>] raw author names (may contain duplicates/nils)
     # @param pattern [String] a NameFormatter pattern or preset name
-    # @return [Hash{String => String}] raw_name → disambiguated formatted name
+    # @return [Hash{String => String}] raw name to disambiguated formatted name
     def resolve(names, pattern)
       pattern = NameFormatter::PRESETS.fetch(pattern, pattern)
       uniq_names = names.compact.reject(&:empty?).uniq
 
-      # Merge names that are the same person (same first+last, differ only in middle)
       canonical, aliases = merge_same_person(uniq_names)
 
-      # Format every canonical name with the base pattern
       result = {}
       canonical.each { |n| result[n] = NameFormatter.format(n, pattern) }
 
-      # Find collision groups (different raw names → same formatted output)
       collisions = find_collisions(result)
       unless collisions.empty?
         tokens = parse_tokens(pattern)
@@ -41,16 +34,14 @@ module Railbow
         end
       end
 
-      # Expand aliases: all variant spellings get the same formatted output
       aliases.each { |variant, canon| result[variant] = result[canon] }
 
       result
     end
 
-    # --- private helpers ---
-
-    # Group names by (first, last) and pick the shortest as canonical.
-    # Returns [canonical_names, aliases_hash] where aliases maps variant → canonical.
+    # Groups names by first and last name; the shortest (no middle name) is
+    # canonical. Returns [canonical_names, aliases], aliases mapping each
+    # variant to its canonical name.
     def merge_same_person(names)
       groups = {}
       names.each do |name|
@@ -66,7 +57,6 @@ module Railbow
       canonical = []
       aliases = {}
       groups.each_value do |group|
-        # Pick shortest name as canonical (the one without middle name)
         canon = group.min_by(&:length)
         canonical << canon
         group.each { |name| aliases[name] = canon unless name == canon }
@@ -81,14 +71,12 @@ module Railbow
         .transform_values { |pairs| pairs.map(&:first) }
     end
 
-    # Resolve a single collision group by progressively expanding tokens.
-    # Only names that still collide continue to be expanded; once a name
-    # becomes unique it keeps its current (minimal) expansion.
+    # Widens tokens, all F tokens before L, only for names that still collide:
+    # a name that becomes unique keeps its shortest distinct form.
     def resolve_group(raw_names, base_pattern, base_tokens, result)
       remaining = raw_names.dup
       tokens = base_tokens.map(&:dup)
 
-      # Expansion order: exhaust all F tokens first, then L tokens
       expansion_order = tokens.each_index.sort_by { |i| (tokens[i][:type] == "F") ? 0 : 1 }
 
       expansion_order.each do |ti|
@@ -102,15 +90,14 @@ module Railbow
 
           remaining.each { |n| result[n] = NameFormatter.format(n, current_pattern) }
 
-          # Check collisions only within this group (not the full result),
-          # so expansion from one group can't chase collisions with other groups
+          # Within this group only, so one group's expansion never chases
+          # collisions with another's.
           still_colliding = find_collisions(result.slice(*raw_names))
           if still_colliding.empty?
             remaining = []
             break
           end
 
-          # Only keep expanding names that still collide within the group
           remaining = still_colliding.values.flatten
         end
 
@@ -119,7 +106,7 @@ module Railbow
 
       return if remaining.empty?
 
-      # Last resort: numeric suffixes
+      # Fully expanded and still equal: number them.
       find_collisions(result.slice(*remaining)).each_value do |group|
         group[1..].each_with_index do |name, i|
           suffix = SUPERSCRIPTS[i] || (i + 2).to_s
@@ -128,7 +115,7 @@ module Railbow
       end
     end
 
-    # Parse pattern into token descriptors: [{type:, length:, maxed:}, ...]
+    # [{type:, length:, maxed:}, ...] for each token in the pattern.
     def parse_tokens(pattern)
       tokens = []
       pattern.scan(NameFormatter::TOKEN_RE) do |match|
@@ -139,7 +126,7 @@ module Railbow
       tokens
     end
 
-    # Rebuild a pattern string from token descriptors, preserving literals.
+    # The original pattern with its tokens resized, literals kept.
     def rebuild_pattern(tokens, original_pattern)
       ti = 0
       original_pattern.gsub(NameFormatter::TOKEN_RE) do

data/lib/railbow/name_formatter.rb

@@ -1,22 +1,22 @@
 # frozen_string_literal: true
 
 module Railbow
-  # Formats person names using a pattern language inspired by date-format strings.
+  # Formats person names with a pattern language modeled on date formats.
   #
-  # Tokens (repeat the letter to control length; 4+ means full word):
-  #   F / FF / FFF / FFFF+  — first name (1 char, 2 chars, … , full)
-  #   L / LL / LLL / LLLL+  — last name
-  #   M / MM / MMM / MMMM+  — middle name(s)
+  # Tokens (the letter count is the length; 4 or more means the full word):
+  #   F / FF / FFF / FFFF+   first name (1 char, 2 chars, 3 chars, full)
+  #   L / LL / LLL / LLLL+   last name
+  #   M / MM / MMM / MMMM+   middle name(s)
   #
   # Any other characters (spaces, dots, commas) are literals and pass through.
   #
   # Named presets:
-  #   "initials"        → "F L"
-  #   "short"           → "FF L"
-  #   "first_name"      → "FFFF"
-  #   "last_name"       → "LLLL"
-  #   "full_name"       → "FFFF MMMM LLLL"
-  #   "full_name_short" → "FFFF L."
+  #   "initials"        => "F L"
+  #   "short"           => "FF L"
+  #   "first_name"      => "FFFF"
+  #   "last_name"       => "LLLL"
+  #   "full_name"       => "FFFF MMMM LLLL"
+  #   "full_name_short" => "FFFF L."
   module NameFormatter
     PRESETS = {
       "initials" => "F L",
@@ -34,8 +34,7 @@ module Railbow
 
     module_function
 
-    # Format a name according to a pattern or preset name.
-    # Returns "" for nil/empty input.
+    # Formats a name by a pattern or preset name. "" for a nil or empty name.
     def format(name, pattern)
       return "" if name.nil? || name.empty?
 
@@ -59,14 +58,14 @@ module Railbow
         expanded.empty? ? EMPTY : expanded
       end
 
-      # Remove sentinels and any adjacent non-letter literals (dots, commas, spaces)
+      # A missing part takes its adjacent literals with it, so "F L." on a
+      # one-word name gives no stray dot.
       result.gsub(/[^a-zA-Z\x00]*\x00[^a-zA-Z\x00]*/, " ")
         .gsub(/  +/, " ")
         .strip
     end
 
-    # Truncate a word to `len` chars (4+ means full), preserving original case
-    # for full words, capitalizing otherwise.
+    # A full word keeps its case; a cut one is capitalized.
     def truncate(word, len)
       return "" if word.nil? || word.empty?