railbow 0.3.0 → 0.5.0

data/lib/railbow/params.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "date"
+require_relative "calendar"
 require_relative "config"
 require_relative "name_formatter"
 require_relative "name_collision_resolver"
@@ -79,6 +80,17 @@ 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.
+    def since_min
+      value = ENV["RBW_SINCE_MIN"] || Config.load["since_min"] || 0
+      [value.to_i, 0].max
+    end
+
     def sort
       (ENV["RBW_SORT"] || Config.load["sort"] || "file").strip.downcase
     end
@@ -214,6 +226,49 @@ module Railbow
       !val.nil?
     end
 
+    # --- Compound: RBW_DB ---
+
+    def db
+      parse_compound(ENV["RBW_DB"] || Config.load["db"])
+    end
+
+    # Render every database in one time-ordered table instead of a section
+    # each. Only meaningful when the databases keep separate migration sets.
+    def db_inline?
+      db["inline"] == true
+    end
+
+    # Draw the full table for every database, including the quiet ones that
+    # would otherwise collapse to a summary line.
+    def db_full?
+      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.
+    def db_focus?
+      db["focus"] == true
+    end
+
+    def db_only
+      Array(db["only"]).select { |v| v.is_a?(String) }
+    end
+
+    def db_skip
+      Array(db["skip"]).select { |v| v.is_a?(String) }
+    end
+
+    # Whether a database, by its database.yml name, is part of this run.
+    def db_included?(name)
+      name = name.to_s
+      only = db_only
+      return only.include?(name) if only.any?
+
+      !db_skip.include?(name)
+    end
+
     # --- Compound: RBW_CALENDAR ---
 
     def calendar
@@ -226,8 +281,26 @@ module Railbow
       calendar["wticks"] == true
     end
 
+    # A separator row per ISO week, the fuller counterpart to wticks.
+    def calendar_wdividers?
+      return false unless view_calendar?
+
+      calendar["wdividers"] == true
+    end
+
+    # Append "· N migrations" to every separator row: how many it introduces.
+    def calendar_counts?
+      return false unless view_calendar?
+
+      calendar["counts"] == true
+    end
+
     def calendar_label
-      calendar["label"] || "%b %Y   W%V"
+      calendar["label"] || Calendar::DEFAULT_MONTH_LABEL
+    end
+
+    def calendar_week_label
+      calendar["wlabel"] || Calendar::DEFAULT_WEEK_LABEL
     end
   end
 end

data/lib/railbow/status/ghosts.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module Railbow
+  module Status
+    # Recovery of "NO FILE" migrations through the optional mighost gem: rows
+    # applied to the database whose migration file is no longer on disk.
+    module Ghosts
+      GHOST_FG = "\e[38;5;217m" # matches Table::Renderer::GHOST_FG, the row it sits in
+      MUTED = "\e[38;5;245m"
+      BRANCH = "\e[38;5;222m"
+
+      # A ghost normalized for rendering, whether it came from mighost's orphan
+      # classification or from a live snapshot recovery.
+      class Row
+        attr_reader :filename, :branch_name, :source, :superseded_by, :deleted_in_sha,
+          :author_name, :author_email, :content
+
+        def initialize(filename: nil, branch_name: nil, source: nil, superseded_by: nil,
+          deleted_in_sha: nil, author_name: nil, author_email: nil, content: nil)
+          @filename = filename
+          @branch_name = branch_name
+          @source = source
+          @superseded_by = superseded_by
+          @deleted_in_sha = deleted_in_sha
+          @author_name = author_name
+          @author_email = author_email
+          @content = content
+        end
+      end
+
+      module_function
+
+      def available?
+        defined?(Mighost::API) && Mighost.enabled?
+      end
+
+      def load(versions, with_content: false)
+        # Detect once: OrphanedMigration carries the classification (supersession,
+        # deletion commit) that a bare snapshot does not, and already honors
+        # dismissals and hide_superseded.
+        orphans = begin
+          Mighost::API.orphaned_migrations.to_h { |o| [o.version.to_s, o] }
+        rescue
+          return {}
+        end
+
+        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.
+          next unless (orphan = orphans[v])
+
+          row = if orphan.filename && !orphan.filename.empty?
+            from_orphan(orphan, v, with_content)
+          else
+            from_live_recovery(v, with_content)
+          end
+          rows[v] = row if row
+        end
+        rows
+      end
+
+      def from_orphan(orphan, version, with_content)
+        Row.new(
+          filename: orphan.filename,
+          branch_name: orphan.branch_name,
+          source: read_attr(orphan, :source),
+          superseded_by: read_attr(orphan, :superseded_by),
+          deleted_in_sha: read_attr(orphan, :deleted_in_sha),
+          author_name: read_attr(orphan, :author_name),
+          author_email: read_attr(orphan, :author_email),
+          content: with_content ? snapshot_content(version) : nil
+        )
+      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.
+      def from_live_recovery(version, with_content)
+        snapshot = begin
+          Mighost::API.find_or_recover_snapshot(version)
+        rescue
+          nil
+        end
+        return nil unless snapshot&.filename && !snapshot.filename.empty?
+
+        Row.new(
+          filename: snapshot.filename,
+          branch_name: snapshot.branch_name,
+          source: read_attr(snapshot, :source),
+          superseded_by: api_superseded_by(version),
+          deleted_in_sha: read_attr(snapshot, :deleted_in_sha),
+          author_name: read_attr(snapshot, :author_name),
+          author_email: read_attr(snapshot, :author_email),
+          content: with_content ? snapshot.content : nil
+        )
+      end
+
+      def read_attr(obj, name)
+        obj.respond_to?(name) ? obj.public_send(name) : nil
+      end
+
+      def snapshot_content(version)
+        Mighost::API.find_snapshot(version)&.content
+      rescue
+        nil
+      end
+
+      def api_superseded_by(version)
+        return nil unless Mighost::API.respond_to?(:superseded_by)
+
+        Mighost::API.superseded_by(version)
+      rescue
+        nil
+      end
+
+      # One tag slot per ghost row; the most informative wins. Each ends in the
+      # ghost foreground rather than a reset, so the rest of the row keeps its
+      # ghost styling.
+      def tag(ghost)
+        if ghost.superseded_by
+          "#{MUTED}≡ #{ghost.superseded_by}#{GHOST_FG}"
+        elsif ghost.branch_name
+          if ghost.source == "worktree"
+            "#{BRANCH}⌥ₜ#{ghost.branch_name}#{GHOST_FG}"
+          else
+            "#{BRANCH}⌥ #{ghost.branch_name}#{GHOST_FG}"
+          end
+        elsif ghost.deleted_in_sha
+          "#{MUTED}✂ deleted in:#{ghost.deleted_in_sha[0, 8]}#{GHOST_FG}"
+        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
+          .sub(/\.rb\z/, "")      # strip extension
+          .tr("_", " ")
+          .gsub(/\b\w/, &:upcase) # titleize
+      end
+    end
+  end
+end

data/lib/railbow/status/git_data.rb

@@ -0,0 +1,327 @@
+# frozen_string_literal: true
+
+require "date"
+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.
+    class GitData
+      EMPTY_AUTHORS = {names: {}, emails: {}}.freeze
+
+      attr_reader :migrate_dir, :author_names, :author_emails, :landed_dates,
+        :git_email, :git_name, :branch_origins, :uncommitted_files,
+        :incoming_merge_files, :merge_source_label
+
+      # migrate_dir is nil when no migration file could be located, in which
+      # case every file-scoped lookup is skipped and the accessors stay empty.
+      def initialize(migrate_dir:, author_enabled:, diff_enabled:, base_override: "", branch_mask: "")
+        @migrate_dir = migrate_dir
+        @author_names = {}
+        @author_emails = {}
+        @landed_dates = {}
+        @branch_origins = {}
+        @uncommitted_files = Set.new
+        @incoming_merge_files = Set.new
+        @merge_source_label = nil
+
+        load_authors(author_enabled)
+        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.
+      def self.for(migrate_dir:, **opts)
+        cache = Railbow::MultiDb.current&.git_cache
+        return new(migrate_dir: migrate_dir, **opts) unless cache
+
+        cache[[migrate_dir, opts]] ||= new(migrate_dir: migrate_dir, **opts)
+      end
+
+      # Extracts a display label from a branch name. "auto" uses the built-in
+      # ticket pattern; anything else is a regex whose first capture wins.
+      def self.apply_branch_mask(branch, branch_mask)
+        return branch if branch_mask.empty?
+        return Railbow::Params.extract_branch_ticket(branch) if branch_mask == "auto"
+
+        re = begin
+          Regexp.new(branch_mask, Regexp::IGNORECASE)
+        rescue RegexpError
+          return branch
+        end
+        m = branch.match(re)
+        (m && m[1]) ? m[1] : branch
+      end
+
+      private
+
+      def apply_branch_mask(branch, branch_mask)
+        self.class.apply_branch_mask(branch, branch_mask)
+      end
+
+      def load_authors(author_enabled)
+        if migrate_dir
+          @landed_dates = migration_landed_dates
+          if author_enabled
+            result = migration_authors
+            @author_names = result[:names]
+            @author_emails = result[:emails]
+          end
+        end
+        return unless author_enabled
+
+        @git_email = current_git_email
+        @git_name = current_git_name
+      end
+
+      def load_diff(branch_mask, base_override)
+        base_branch = detect_default_branch(base_override)
+        @branch_origins = branch_migration_origins(base_branch, branch_mask)
+        @incoming_merge_files = incoming_merge_files_from_git
+        @merge_source_label = detect_merge_source_label(branch_mask) if @incoming_merge_files.any?
+        @uncommitted_files = uncommitted_migration_files
+
+        # Uncommitted files have no commit to attribute, so they belong to
+        # whatever branch is checked out right now.
+        current_branch = current_branch_name(branch_mask)
+        @uncommitted_files.each { |f| @branch_origins[f] ||= current_branch }
+      end
+
+      def migration_authors
+        output, _status = Railbow::GitUtils.capture2(
+          "log", "--format=COMMIT:%aN\t%aE", "--diff-filter=AR", "--name-status", "--", migrate_dir
+        )
+        return EMPTY_AUTHORS.dup if output.empty?
+
+        names = {}
+        emails = {}
+        current_name = nil
+        current_email = nil
+        output.each_line do |line|
+          line = line.strip
+          if line.start_with?("COMMIT:")
+            parts = line.sub("COMMIT:", "").split("\t", 2)
+            current_name = parts[0]
+            current_email = parts[1]&.downcase
+          elsif !line.empty? && current_name
+            basename = name_status_basename(line)
+            next unless basename
+            names[basename] ||= current_name
+            emails[basename] ||= current_email
+          end
+        end
+        {names: names, emails: emails}
+      end
+
+      # basename => Date the migration first appeared on the mainline (the
+      # merge commit date, via --first-parent).
+      def migration_landed_dates
+        output, _status = Railbow::GitUtils.capture2(
+          "log", "--first-parent", "--format=COMMIT:%cI", "--diff-filter=AR", "--name-status", "--", migrate_dir
+        )
+        return {} if output.empty?
+
+        dates = {}
+        current_date = nil
+        output.each_line do |line|
+          line = line.strip
+          if line.start_with?("COMMIT:")
+            current_date = begin
+              Date.parse(line.sub("COMMIT:", ""))
+            rescue Date::Error
+              nil
+            end
+          elsif !line.empty? && current_date
+            basename = name_status_basename(line)
+            next unless basename
+            dates[basename] ||= current_date
+          end
+        end
+        dates
+      end
+
+      # --name-status lines are "A\tfilepath" or "Rnnn\told\tnew"; a rename
+      # attributes to its destination.
+      def name_status_basename(line)
+        cols = line.split("\t")
+        filepath = cols[0]&.start_with?("R") ? cols[2] : cols[1]
+        filepath ? File.basename(filepath) : nil
+      end
+
+      def current_git_email
+        output, _status = Railbow::GitUtils.capture2("config", "user.email")
+        output.strip.downcase
+      end
+
+      def current_git_name
+        output, _status = Railbow::GitUtils.capture2("config", "user.name")
+        output.strip
+      end
+
+      def current_branch_name(branch_mask)
+        output, status = Railbow::GitUtils.capture2("rev-parse", "--abbrev-ref", "HEAD")
+        return "HEAD" unless status.success?
+
+        apply_branch_mask(output.strip, branch_mask)
+      end
+
+      def detect_default_branch(override)
+        return override if override && !override.empty?
+
+        output, status = Railbow::GitUtils.capture2("symbolic-ref", "refs/remotes/origin/HEAD")
+        if status.success?
+          branch = output.strip.sub(%r{^refs/remotes/origin/}, "")
+          return branch unless branch.empty?
+        end
+
+        %w[main master].each do |candidate|
+          _, st = Railbow::GitUtils.capture2("rev-parse", "--verify", "refs/heads/#{candidate}")
+          return candidate if st.success?
+        end
+
+        "main"
+      end
+
+      def branch_migration_origins(base_branch, branch_mask)
+        merge_base_out, mb_status = Railbow::GitUtils.capture2("merge-base", "HEAD", base_branch)
+        return {} unless mb_status.success?
+
+        merge_base = merge_base_out.strip
+        diff_out, diff_status = Railbow::GitUtils.capture2(
+          "diff", "--name-status", "--diff-filter=AR", merge_base, "HEAD", "--", migrate_dir
+        )
+        return {} unless diff_status.success?
+
+        files = diff_out.each_line.map { |l|
+          cols = l.strip.split("\t")
+          cols[0]&.start_with?("R") ? cols[2] : cols[1]
+        }.compact.reject(&:empty?)
+        origins = {}
+
+        files.each do |filepath|
+          basename = File.basename(filepath)
+          commit = adding_commit(filepath)
+          next unless commit
+
+          branches = branches_containing(commit)
+          next if branches.empty?
+
+          best = pick_origin_branch(branches, commit)
+          origins[basename] = best ? apply_branch_mask(best, branch_mask) : best
+        end
+
+        origins
+      end
+
+      def adding_commit(filepath)
+        commit_out, cs = Railbow::GitUtils.capture2(
+          "log", "--diff-filter=AR", "--format=%H", "-1", "--", filepath
+        )
+        return nil unless cs.success?
+
+        commit = commit_out.strip
+        commit.empty? ? nil : commit
+      end
+
+      def branches_containing(commit)
+        branches_out, bs = Railbow::GitUtils.capture2(
+          "branch", "--contains", commit, "--format=%(refname:short)"
+        )
+        return [] unless bs.success?
+
+        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.
+      def pick_origin_branch(branches, commit)
+        return branches.first if branches.size == 1
+
+        filtered = branches.reject do |b|
+          branches.any? do |other|
+            next false if other == b
+            _, st = Railbow::GitUtils.capture2("merge-base", "--is-ancestor", other, b)
+            st.success?
+          end
+        end
+        filtered = branches if filtered.empty?
+        return filtered.first if filtered.size == 1
+
+        filtered.max_by do |b|
+          count_out, _ = Railbow::GitUtils.capture2("rev-list", "--count", "#{commit}..#{b}")
+          count_out.strip.to_i
+        end
+      end
+
+      def uncommitted_migration_files
+        output, status = Railbow::GitUtils.capture2("status", "--porcelain", "--", migrate_dir)
+        return Set.new unless status.success?
+
+        result = Set.new
+        output.each_line do |line|
+          code = line[0..1]
+
+          if code[0] == "R"
+            # Rename: "R  old -> new" or "R100 old -> new". Take the destination.
+            parts = line[3..].split(" -> ", 2)
+            filepath = (parts[1] || parts[0]).strip
+          elsif ["??", "A ", "AM", "M "].include?(code)
+            filepath = line[3..].strip
+          else
+            next
+          end
+
+          result << File.basename(filepath) unless filepath.empty?
+        end
+
+        # During an in-progress merge, files from MERGE_HEAD (e.g. main) show up
+        # as staged additions. Exclude them so they are not tagged as ours.
+        result - incoming_merge_files_from_git
+      end
+
+      def detect_merge_source_label(branch_mask)
+        merge_head, _, status = Railbow::GitUtils.capture3("rev-parse", "MERGE_HEAD")
+        return nil unless status.success?
+
+        branches_out, _, bs = Railbow::GitUtils.capture3(
+          "branch", "--contains", merge_head.strip, "--format=%(refname:short)"
+        )
+        return nil unless bs.success?
+
+        branches = branches_out.each_line.map(&:strip).reject(&:empty?)
+        return nil if branches.empty?
+
+        branch = branches.first if branches.size == 1
+        branch ||= branches.find { |b| %w[main master develop].include?(b) }
+        branch ||= branches.first
+
+        apply_branch_mask(branch, branch_mask)
+      end
+
+      def incoming_merge_files_from_git
+        _, _, mh_status = Railbow::GitUtils.capture3("rev-parse", "MERGE_HEAD")
+        return Set.new unless mh_status.success?
+
+        output, _, status = Railbow::GitUtils.capture3(
+          "diff", "--name-only", "--diff-filter=AR", "HEAD", "MERGE_HEAD", "--", migrate_dir
+        )
+        return Set.new unless status.success?
+
+        Set.new(output.each_line.map { |l| File.basename(l.strip) }.reject(&:empty?))
+      end
+    end
+  end
+end

data/lib/railbow/status/help.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require_relative "../logo"
+
+module Railbow
+  module Status
+    module Help
+      module_function
+
+      def print
+        Railbow.print_logo
+        puts <<~HELP
+
+          Enhanced db:migrate:status
+
+          \e[1mUsage:\e[0m
+            [RBW_*=value ...] rake db:migrate:status
+
+          \e[1mOptions:\e[0m
+            RBW_SINCE=<period>       Filter migrations by age (default: all)
+                                     Values: all, 2mo, 1w, 30d, 1y, etc.
+                                     Units: d (days), w (weeks), mo/m (months), y (years)
+
+            RBW_SINCE_MIN=<n>        Never show fewer than n migrations, however
+                                     old (default: 10). The window above is a
+                                     soft limit: a database with five migrations
+                                     shows all five rather than reporting an
+                                     empty period. 0 disables the floor.
+
+            RBW_DATE=<mode>          Date column format (default: full):
+                                     full       - 2026-01-30 12:08:54 (column: Created At)
+                                     rel        - ~3d ago
+                                     short      - Jan 30 (column: Date)
+                                     custom(…)  - user strftime, e.g. custom(%b %d, %Y)
+
+            RBW_VIEW=<options>       Display options (comma-separated):
+                                     calendar   - show month/year separator lines + week ticks
+                                     tables     - parse migration files, show Tables column
+
+            RBW_COMPACT=<options>    Compact display (comma-separated):
+                                     oneline    - truncate instead of wrapping
+                                     dense      - remove cell padding
+                                     noheader   - hide table header row
+                                     maxw:<n>   - cap column widths at n chars
+                                     hide:<col> - hide a column by name (repeatable)
+
+            RBW_CALENDAR=<options>   Calendar sub-options (requires RBW_VIEW=calendar):
+                                     (empty)      - month separators only, no week
+                                                    markers at all
+                                     wticks       - week tick marks on the date column
+                                     wdividers    - a separator row per ISO week
+                                     counts       - append "· N migrations" to every
+                                                    separator row (that section)
+                                     label:<fmt>  - strftime for month separators
+                                                    (default: %b %Y   W%V)
+                                     wlabel:<fmt> - strftime for week separators
+                                                    (default: same as label, so the
+                                                    week number never shifts)
+
+            RBW_DB=<options>         Multi-database runs (default: focus).
+                                     An empty value expands every database into
+                                     its own section, in database.yml order,
+                                     with column widths shared so the tables
+                                     line up. Databases sharing a migrations
+                                     path (shards) merge into one table with a
+                                     status per database.
+                                     focus        - expand only the first
+                                                    database, summarizing the
+                                                    rest in a line each. A
+                                                    database with migrations
+                                                    pending is always expanded
+                                     only:<name>  - render only this database
+                                                    (repeatable)
+                                     skip:<name>  - drop this database
+                                                    (repeatable)
+                                     full         - draw every database in full,
+                                                    overriding focus and never
+                                                    collapsing a quiet one
+                                     inline       - one merged table ordered by
+                                                    version, with a Db column
+
+            RBW_GIT=<options>        Git integration (comma-separated):
+                                     author     - add an Author column (same as author:all)
+                                     author:all - add an Author column
+                                     author:me  - highlight your own migrations
+                                     diff       - tag migrations by git origin
+                                     base:<branch> - base branch for diff (default: auto-detected)
+                                     mask:<re>  - regex to extract branch label
+                                                  e.g. mask:(WS-[^/]+)/
+                                     mask:auto  - auto-extract ticket id from branch name
+
+            RBW_PLAIN=1              Disable Railbow formatting (plain Rails output)
+
+            RBW_FORCE=1              Force Railbow formatting even when piped, in CI,
+                                     or called by an LLM agent (RBW_PLAIN=1 still wins)
+
+            RBW_HELP=1               Show this help message
+
+          \e[2mAuto-disabled when piped, in CI, or when called by an LLM agent.\e[0m
+
+          \e[1mExamples:\e[0m
+            rake db:migrate:status
+            RBW_SINCE=2mo RBW_VIEW=calendar rake db:migrate:status
+            RBW_CALENDAR=wdividers,counts rake db:migrate:status
+            RBW_VIEW=tables RBW_GIT=author rake db:migrate:status
+            RBW_GIT=author:me RBW_SINCE=3mo rake db:migrate:status
+            RBW_DATE=rel rake db:migrate:status
+            RBW_DATE=short rake db:migrate:status
+            RBW_DATE='custom(%b %d, %Y)' rake db:migrate:status
+            RBW_GIT=diff rake db:migrate:status
+            RBW_GIT=diff,base:develop rake db:migrate:status
+            RBW_GIT=diff,mask:(WS-[^/]+)/ rake db:migrate:status
+            RBW_DB= rake db:migrate:status
+            RBW_DB=only:primary rake db:migrate:status
+            RBW_DB=inline rake db:migrate:status
+
+        HELP
+      end
+    end
+  end
+end