railbow 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 55d44fb326ce90c9bc4e843104639b49c2d96c866401bb53c962f226166bb22f
-  data.tar.gz: 808baadb49bf2e7d96586a1a809501bdbe87cfa454db019d184ca36804cc813a
+  metadata.gz: d599ddd7c1bd3a12893312ab22f40ff75def87f5d85d42dd2ee5a11da7183225
+  data.tar.gz: 4413568aafb22c8cf2b1025bbd6f90696f4da6f3bcead307c48ffeac3e96f04c
 SHA512:
-  metadata.gz: c256343dee985473f88c27aa26e0bb827587d49001eaf82f7a8d85dbf3a56197d65ba12e3641d64c87cfbcac290a2b787020d1850a53ce0e8fbf746dc2d3ef9e
-  data.tar.gz: 4d5740b3a9a98aa692b7b031fa26a811709c4724c996ee9dfd00f0dfc3f339bf431499c27c3af46b354a7aeb7ae9bd95503f99402b1d5e44f3b1fc6314cd64a1
+  metadata.gz: a02d2dda50ba6fa9ae4b04d166ebc51148532dcfccd5ab1a7777179d14767d2bb87b2fc4a9a5d3aadbb0eeae114a68f5365cd3bfd0d27286958b192f5fa43967
+  data.tar.gz: 5ad80b381822e25a9078093f82c8b52deccae5940334ce45645883e2d4c06a81070e2710876f58fc8af949cc3b96009369e141eb9945c3a1941233561c31f486

data/CHANGELOG.md

@@ -5,6 +5,60 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0] - 2026-07-28
+
+### Added
+
+- Multi-database support for `db:migrate:status`. Rails runs the task once per
+  database; railbow now wraps that loop and renders the databases together, as
+  one section each in `database.yml` order with column widths shared so the
+  tables line up. The section header names the database by its `database.yml`
+  name, which is what you configure and filter by, rather than the database
+  name Rails reports.
+- A database with nothing in the time window and nothing pending collapses to a
+  one-line summary instead of an empty table, so the `cache`, `queue` and
+  `cable` databases of a stock Rails 8 app stop drowning out your own. Anything
+  it hides (pending migrations, ghosts) is counted in the line, along with the
+  flag that reveals them.
+- Databases sharing a `migrations_paths` (horizontal sharding) merge into a
+  single table carrying a status glyph per database, making drift between
+  shards visible at a glance. A dim `·` marks a version one shard has never
+  seen.
+- `RBW_DB` (config key `db`) selects and shapes a multi-database run:
+  `only:<name>` and `skip:<name>` (both repeatable) pick databases, `full`
+  draws the quiet ones in full, and `inline` merges everything into one table
+  ordered by version with a `Db` column, so the calendar spans the whole
+  application instead of restarting per database. Filtered-out databases are
+  named in a footer rather than silently dropped.
+
+- `RBW_SINCE_MIN` (config key `since_min`, default 10) makes the time window a
+  soft limit: whatever `since` leaves, the floor tops it back up to this many
+  migrations. A database with five migrations now shows all five rather than
+  hiding the two that happen to be old and reporting an empty period. The
+  hidden-count line says `showing the last 10` when the floor overrode the
+  window, and a multi-database section header reads `last 10 of 50` rather than
+  `10 of 50`, so a table holding rows older than the window it names still
+  reads honestly in both views. `RBW_SINCE_MIN=0` restores the old hard cutoff.
+- `RBW_DB=focus`, **the default**, expands only the first database and
+  summarizes the rest in a line each, so a multi-database app is one table to
+  read rather than several. A database holding pending migrations is expanded
+  anyway: the summary exists to hide what needs no action, and pending work is
+  the opposite of that. An empty `RBW_DB` (or `db: ""`) expands every database
+  that has recent activity, `full` expands everything including quiet ones, and
+  `focus` never applies to an `inline` run, which exists to hold every database
+  at once.
+
+### Changed
+
+- Git lookups are now shared across a run: authors, landed dates and branch
+  origins are resolved once per migrations directory instead of once per
+  database. `RBW_HELP=1` prints the help once for the whole run rather than
+  once per database.
+- `db:migrate:status` internals moved out of the rake file into
+  `Railbow::Status` (`Section`, `Printer`, `GitData`, `Ghosts`, `Help`). No
+  output changed: a single-database app renders byte for byte what it did
+  before, which a golden fixture now enforces.
+
 ## [0.4.0] - 2026-07-28
 
 ### Added

data/README.md

@@ -22,6 +22,7 @@
 - **About** - polished `rails about` output
 - **Git Integration** - authors, diffs, branch origin, landing dates, uncommitted file indicators
 - **Calendar View** - month separators plus week ticks or full week rows, with optional per-section counts
+- **Multiple Databases** - read one table by default, the rest summarized in a line each (and expanded when they have migrations pending); sharded databases merged with a status per shard
 - **Ghost Recovery** - uses the [mighost](https://github.com/amberpixels/mighost) gem (optional) to recover names, authors, and branch badges for `NO FILE` migrations
 - **Smart Defaults** - auto-disables in CI, piped output, `NO_COLOR`, and LLM agents
 
@@ -103,7 +104,7 @@ Out of the box you get:
 - **Landing dates** - `⤻ Mar 04` badge when a migration was merged to main after its creation
 - **Branch badges** - `⎇ PS-142` showing the source branch/ticket
 - **Affected tables** - color-coded table names extracted from migration files
-- **Time filtering** - only the last 70 days shown by default (`since: 70d`)
+- **Time filtering** - only the last 70 days shown by default (`since: 70d`), as a soft limit: never fewer than 10 migrations, however old (`since_min: 10`)
 - **Your migrations highlighted** - rows authored by you are visually distinct
 - **Pending migrations greyed out** - a `down` row keeps its status glyph but loses its colors
 
@@ -146,6 +147,79 @@ calendar: ""            # month separators only
 
 Dropping `calendar` from `view` instead removes the month separators too.
 
+#### Multiple databases
+
+Rails runs `db:migrate:status` once per database, so a multi-database app used
+to get one blind table per database: widths that did not line up, the help
+printed once per database, and every git lookup repeated. Railbow now renders
+the whole run together.
+
+By default you read one table: the first database in `database.yml` is rendered
+in full and every other one is summarized in a line each (`db: focus`).
+
+```
+📊 2 databases · primary, raw
+
+──── primary · myapp_development ──── 122 of 1500 ──────────────────────
+ ↑↑  │ 20260721130000 │ 2026-07-21 13:00:00 │ Partition sms notifications  ● sms_notifications
+ ↓↓  │ 20260727170000 │ 2026-07-27 17:00:00 │ Add cr push columns to lines ● lines
+
+⋯ raw · 5 migrations, all applied · latest Jul 22 2026
+```
+
+**A database with migrations pending is always expanded**, however focused the
+run is. The summary exists to hide what needs no action, and pending work is
+the opposite of that.
+
+Setting `db` to an empty value expands every database that has recent activity,
+each as its own section with column widths shared so the tables line up:
+
+```yaml
+db: ""            # or RBW_DB= on the command line
+```
+
+```
+──── primary · myapp_development ──── 122 of 1500 ──────────────────────
+ ↑↑  │ 20260721130000 │ 2026-07-21 13:00:00 │ Partition sms notifications  ● sms_notifications
+
+──── raw · raw_development ─────────────────────────────────────────────
+ ↑↑  │ 20260722120000 │ 2026-07-22 12:00:00 │ Drop archived activity logs  ● archived_activity_logs
+```
+
+A section header counts what it is showing: `122 of 1500` means 122 fell inside
+the time window. When the window found too few and the `since_min` floor topped
+the section back up, it reads `last 10 of 50` instead, because the rows are
+then the newest ten rather than a window's worth.
+
+Even then, a database with nothing in the time window collapses to one line
+rather than an empty table, which is what keeps the `cache`, `queue` and
+`cable` databases of a stock Rails 8 app from drowning out your own:
+
+```
+⋯ cache · 5 migrations, all applied · latest Feb 12 2024
+⋯ queue · 12 migrations, 3 pending outside the 70d window - RBW_SINCE=all
+```
+
+Databases that share a `migrations_paths` (horizontal sharding) run the same
+files, so they merge into one table carrying a status per database. Drift
+between shards is then visible at a glance, and `·` marks a version a shard has
+never seen:
+
+```
+──── primary + primary_shard_one · db/migrate ──────────────────────────
+ ↑↑ ↑↑ │ 20260601151200 │ 2026-06-01 15:12:00 │ Add owner id to pets
+ ↑↑ ↓↓ │ 20260726143000 │ 2026-07-26 14:30:00 │ Add policy number to bills
+```
+
+`RBW_DB` controls the rest: `only:<name>` and `skip:<name>` (both repeatable)
+pick databases, `full` draws every section in full and overrides `focus`, and
+`inline` merges everything into a single table ordered by version with a `Db`
+column, so the calendar spans the whole application rather than restarting per
+database. `focus` never applies to an inline run - a merged table exists to
+hold every database at once.
+
+A single-database app sees none of this: its output is unchanged.
+
 If the [mighost](https://github.com/amberpixels/mighost) gem is installed (`gem "mighost", group: [:development, :test]`), migrations whose files were deleted (e.g. after switching branches) show up with a 👻 status and their recovered name instead of a bare `********** NO FILE **********` row - Railbow talks to it through the stable `Mighost::API`. Each ghost row carries the most informative badge mighost can provide: `≡ <version>` when the migration was re-timestamped and lives on under another version (shown with a calmer 🪦 status), `⌥ <branch>` when a branch still holds the file, or `✂ deleted in:<sha>` pointing at the commit that removed it. Ghosts dismissed via `mighost:dismiss` (or hidden by `hide_superseded`) render as plain `NO FILE`.
 
 ### `rails db:migrate:down`
@@ -193,10 +267,12 @@ rake railbow:init
 
 ```yaml
 since: 70d
+since_min: 10
 date: rel
 git: "author:me,diff,mask:auto"
 view: "calendar,tables"
 calendar: wticks
+db: focus
 
 compact: "maxw:120"
 
@@ -218,10 +294,12 @@ Every option can also be set via `RBW_*` environment variables, which override c
 | `RBW_PLAIN` | `1` | Disable all formatting |
 | `RBW_FORCE` | `1` | Force formatting even when piped, in CI, or run by an LLM agent (`RBW_PLAIN=1` still wins) |
 | `RBW_SINCE` | `2mo`, `70d`, `1y`, `all` | Filter migrations by time period |
+| `RBW_SINCE_MIN` | `10`, `0` | Never show fewer than this many migrations, however old (default 10; `0` disables) |
 | `RBW_DATE` | `full`, `rel`, `short`, `custom(%b %d)` | Date display format |
 | `RBW_GIT` | `author:me,diff,mask:auto` | Git integration options |
 | `RBW_VIEW` | `calendar,tables` | Enable calendar view and table detection |
 | `RBW_CALENDAR` | `wticks`, `wdividers,counts`, `` (empty) | Week markers: tick marks, full week separator rows, per-section counts. Empty means month separators only |
+| `RBW_DB` | `focus` (default), `` (empty), `only:primary`, `skip:cache`, `full`, `inline` | Multi-database runs: focus one database, expand them all, pick some, or merge them into one table |
 | `RBW_COMPACT` | `oneline,dense,noheader,maxw:80` | Compact display options |
 | `RBW_VERB` | `GET,POST` | Filter routes by HTTP method |
 | `RBW_SORT` | `file`, `date` | Sort order for notes |

data/lib/railbow/config.rb

@@ -14,10 +14,12 @@ module Railbow
         }
       },
       "since" => "70d",
+      "since_min" => 10,
       "git" => "author:all,diff,mask:auto",
       "author_format" => "short",
       "view" => "calendar,tables",
-      "calendar" => "wticks"
+      "calendar" => "wticks",
+      "db" => "focus"
     }.freeze
 
     @root = nil

data/lib/railbow/init.rb

@@ -22,6 +22,11 @@ module Railbow
       # Time window for migrations to display (e.g. 30d, 2mo, 1y, all)
       since: "70d"
 
+      # Never show fewer than this many migrations, however old they are.
+      # 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.
+      since_min: 10
+
       # Sort order: file (by filename/version) or date (by timestamp)
       # sort: "file"
 
@@ -55,6 +60,17 @@ module Railbow
       # Date format: full, rel, short, or custom(%b %d, %Y)
       # date: "full"
 
+      # 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.
+      #   focus       - expand only the first database, summarizing the rest.
+      #                 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
+      #   inline      - one merged table ordered by version, with a Db column
+      db: "focus"
+
       # Compact mode (comma-separated):
       #   oneline       - one line per migration
       #   dense         - reduce padding

data/lib/railbow/multi_db.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Railbow
+  # Rails runs db:migrate:status once per database, inside
+  # with_temporary_pool_for_each. Each call on its own cannot know whether more
+  # databases are coming, so railbow wraps that loop: sections collect into the
+  # open batch and the batch renders them together when the loop ends.
+  #
+  # A batch is inert unless something adds to it, so wrapping the other tasks
+  # that share the same Rails helper (db:migrate, db:prepare) costs one object.
+  module MultiDb
+    KEY = :railbow_multi_db_batch
+
+    class Batch
+      attr_reader :git_cache
+
+      def initialize
+        @sections = []
+        @skipped = []
+        @git_cache = {}
+        @help_shown = false
+      end
+
+      # A database excluded by RBW_DB. Recorded rather than dropped so the run
+      # can say what it left out.
+      def skip(name)
+        @skipped << name.to_s
+      end
+
+      # Databases sharing a migrations path see the same files, so they merge
+      # into one section that carries a status per database.
+      def add(section)
+        existing = @sections.find { |s| s.same_migrations?(section) }
+        if existing
+          existing.merge!(section)
+        else
+          @sections << section
+        end
+      end
+
+      def claim_help
+        return false if @help_shown
+
+        @help_shown = true
+      end
+
+      def empty?
+        @sections.empty? && @skipped.empty?
+      end
+
+      def flush
+        return if empty?
+
+        Railbow::Status::Printer.new(@sections, skipped: @skipped).print
+        @sections = []
+        @skipped = []
+      end
+    end
+
+    module_function
+
+    # Opens a batch for the duration of the block. The flush is in an ensure so
+    # that a database aborting mid-run (a missing schema_migrations table, say)
+    # still prints the sections collected before it.
+    def batch
+      previous = Thread.current[KEY]
+      batch = Batch.new
+      Thread.current[KEY] = batch
+      begin
+        yield
+      ensure
+        Thread.current[KEY] = previous
+        batch.flush
+      end
+    end
+
+    def current
+      Thread.current[KEY]
+    end
+
+    # True the first time it is asked within a run. Without a batch every call
+    # is its own run, so the answer is always true.
+    def claim_help
+      current ? current.claim_help : true
+    end
+  end
+end

data/lib/railbow/params.rb

@@ -80,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
@@ -215,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

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