railbow 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 783c8ab9f75f889cd1c54cd36dbc258e06b411b9ae5132af6815564f83d73312
+  data.tar.gz: 1200e9edbd432786044d0ac0992773de513390e787500eecd48dc745a473da4e
+SHA512:
+  metadata.gz: be4c900efd96d11e1d896eb0facd145a928fc93b2b08d30b02cf14a3638e0cf5f133f0c929d037cf828cb3862387ad63725cbbc1cdad4fb84afa353b77ef32fe
+  data.tar.gz: 5231639b5beaefce4ee54e9d0e81b0309d8370b66e4cb7ca9a0e496ad64d0bebcd8b8a69458fe056789947a216e6b6cbdd3c8ad0fb442ddfebf38d25cbf196b8

data/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+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.1.0] - 2026-07-08
+
+First public release.
+
+### Added
+
+- Colorful `db:migrate` / `db:migrate:down` output with readable millisecond
+  timing.
+- Rich `db:migrate:status` dashboard: calendar view with month/week
+  separators, status aliases, created-at timestamps, landing-date badges,
+  branch badges, affected-table detection, time filtering, and highlighting
+  of your own migrations.
+- Git integration: authors, diffs, branch origin, landing dates, and
+  uncommitted-file indicators.
+- Ghost migration recovery in `db:migrate:status` via the optional
+  [mighost](https://github.com/amberpixels/mighost) gem (`Mighost::API`).
+- Color-coded `rails routes`, `rails stats` tables, `rails notes` with git
+  blame, and polished `rails about`.
+- Layered configuration: built-in defaults, `~/.config/railbow/config.yml`,
+  `.railbow.yml`, `.railbow.local.yml`, and `RBW_*` environment variables;
+  interactive `railbow init` / `rake railbow:init` generator.
+- `railbow` CLI wrapper to use Railbow without touching a project's Gemfile,
+  plus `railbow demo` showcase.
+- Smart auto-disable in CI, piped output, `NO_COLOR`, and LLM agents.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Eugene
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,243 @@
+<p align="center">
+  <img src="logo.svg" alt="Railbow" width="580">
+</p>
+
+<div align="center">
+
+[![Gem Version](https://img.shields.io/gem/v/railbow)](https://rubygems.org/gems/railbow)
+[![CI](https://github.com/amberpixels/railbow/actions/workflows/ci.yml/badge.svg)](https://github.com/amberpixels/railbow/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE.txt)
+
+</div>
+
+**Make your Rails CLI output beautiful.** Railbow enhances migrations, routes, stats, notes, and more with colorful, emoji-rich, information-dense formatting.
+
+## Features
+
+- **Migrations** - colorful `db:migrate` output with readable millisecond timing
+- **Migration Status** - rich `db:migrate:status` with git authors, calendar view, table detection, landing dates, and time filtering
+- **Routes** - color-coded HTTP verbs and highlighted parameters in `rails routes`
+- **Stats** - beautiful `rails stats` tables
+- **Notes** - `rails notes` with git blame, author colors, date filtering, and sorting
+- **About** - polished `rails about` output
+- **Git Integration** - authors, diffs, branch origin, landing dates, uncommitted file indicators
+- **Calendar View** - month separators and week tick markers for migration timelines
+- **Ghost Recovery** - pairs with the optional [mighost](https://github.com/amberpixels/mighost) gem to recover names, authors, and branch badges for `NO FILE` migrations
+- **Smart Defaults** - auto-disables in CI, piped output, `NO_COLOR`, and LLM agents
+
+## Installation
+
+### Option A: Add to your Gemfile (recommended)
+
+```ruby
+gem "railbow", group: :development
+```
+
+```bash
+bundle install
+```
+
+### Option B: Use the CLI wrapper (no Gemfile changes)
+
+```bash
+gem install railbow
+railbow rake db:migrate:status
+railbow rails routes
+```
+
+The CLI creates a temporary wrapper so Railbow loads automatically without modifying your project's Gemfile.
+
+## Usage
+
+Railbow works automatically once installed. Every example below works with both `rails` and `rake` commands.
+
+### `rails db:migrate`
+
+**Before:**
+```
+==  CreateProducts: migrating =================================================
+-- create_table(:products)
+   -> 0.0028s
+==  CreateProducts: migrated (0.0028s) ========================================
+```
+
+**After:**
+```
+🚀 CreateProducts: migrating...
+  ✓ create_table(:products) → 2.8ms
+✅ CreateProducts: migrated (2.8ms total)
+```
+
+### `rails db:migrate:status`
+
+This is Railbow's flagship feature. The plain Rails output:
+
+```
+Status   Migration ID    Migration Name
+--------------------------------------------------
+up       20260202145343  Add weight field to animals
+up       20260203134528  Create vaccination records
+up       20260210183902  Create pet tags
+up       20260303120000  Add breed restrictions to adoption policies
+up       20260313132325  Create veterinary appointments
+```
+
+becomes a rich, information-dense dashboard (with default config):
+
+```
+         Feb 2026   W06
+ ↑↑    │ 20260202145343 │ 2026-02-02 14:53:43 │ Add weight field to animals          ● animals
+ ↑↑    │ 20260203134528 │ 2026-02-03 13:45:28 │ Create vaccination records           ● vaccination_records
+ ↑↑    │ 20260210183902 │ 2026-02-10 18:39:02 │ Create pet tags              ⤻ Mar 04  ● pet_tags
+───────┼────────────────┼─────────────────────┼──────────────────────────────
+         Mar 2026   W10
+ ↑↑    │ 20260303120000 │ 2026-03-03 12:00:00 │ Add breed restrictions to…   ⤻ Mar 13  ● adoption_policies
+ ↑↑    │ 20260313132325 │ 2026-03-13 13:23:25 │ Create veterinary appointm…  ⎇ PS-142  ● veterinary_appointments
+```
+
+Out of the box you get:
+
+- **Calendar separators** — month + ISO week headers to orient you in time
+- **Status aliases** — `↑↑` / `↓↓` instead of `up` / `down` (customizable)
+- **Created At** — timestamp parsed from the migration ID
+- **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`)
+- **Your migrations highlighted** — rows authored by you are visually distinct
+
+If the [mighost](https://github.com/amberpixels/mighost) gem is installed, migrations whose files were deleted (e.g. after switching branches) show up with a 👻 status and their recovered name and origin branch instead of a bare `********** NO FILE **********` row.
+
+### `rails db:migrate:down`
+
+```
+⏪ CreateProducts: reverting...
+  ✓ drop_table(:products) → 1.2ms
+✅ CreateProducts: reverted (1.2ms total)
+```
+
+### `rails routes`
+
+HTTP verbs are color-coded (GET=green, POST=yellow, PATCH/PUT=cyan, DELETE=red), route parameters (`:id`, `*splat`) are highlighted, and controller#action pairs stand out.
+
+### `rails stats`
+
+Code statistics rendered as a colorful table with highlighted totals and code-to-test ratio.
+
+### `rails notes`
+
+Annotations enriched with git blame data — author names, commit dates, and color-coded tags (TODO=yellow, FIXME=red, OPTIMIZE=cyan, HACK=red, NOTE=green).
+
+## Configuration
+
+Railbow works with zero configuration, but everything is customizable.
+
+### Config files
+
+Config is loaded in layers (each overrides the previous):
+
+1. **Built-in defaults**
+2. **Global:** `~/.config/railbow/config.yml`
+3. **Project:** `.railbow.yml` (commit to git)
+4. **Local:** `.railbow.local.yml` (gitignored, personal overrides)
+
+Generate a config interactively:
+
+```bash
+railbow init
+# or, within a Rails project:
+rake railbow:init
+```
+
+### Example `.railbow.yml`
+
+```yaml
+since: 70d
+date: rel
+git: "author:me,diff,mask:auto"
+view: "calendar,tables"
+calendar: wticks
+
+compact: "maxw:120"
+
+aliases:
+  columns:
+    Status: Live
+  values:
+    Status:
+      up: "↑↑"
+      down: "↓↓"
+```
+
+### Environment variables
+
+Every option can also be set via `RBW_*` environment variables, which override config files:
+
+| Variable | Example | Description |
+|---|---|---|
+| `RBW_PLAIN` | `1` | Disable all formatting |
+| `RBW_SINCE` | `2mo`, `70d`, `1y`, `all` | Filter migrations by time period |
+| `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` | Show week tick markers |
+| `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 |
+| `RBW_HELP` | `1` | Show help messages |
+
+### Quick examples
+
+```bash
+# Last 2 months, calendar view
+RBW_SINCE=2mo rake db:migrate:status
+
+# Relative dates, highlight your migrations
+RBW_DATE=rel RBW_GIT=author:me rake db:migrate:status
+
+# Full git context with table detection
+RBW_GIT=author:all,diff RBW_VIEW=tables rake db:migrate:status
+
+# Only GET routes
+RBW_VERB=GET rails routes
+
+# Notes sorted by commit date
+RBW_SORT=date rails notes
+```
+
+## How It Works
+
+Railbow integrates through a Rails Railtie — it prepends formatter modules onto existing Rails classes without modifying your code:
+
+- `ActiveRecord::Migration` - migration output
+- `ActiveRecord::Tasks::DatabaseTasks` - migration status
+- `ActionDispatch::Routing::ConsoleFormatter::Sheet` - routes
+- `Rails::Info` - about
+- `Rails::SourceAnnotationExtractor` - notes
+
+Formatting auto-disables when:
+- `RBW_PLAIN=1` or `NO_COLOR` is set
+- Running in CI (`CI` env var)
+- Output is piped or redirected (non-TTY)
+- Running inside an LLM agent (`CLAUDECODE` env var)
+
+## Requirements
+
+- Ruby >= 3.1.0
+- Rails >= 7.2 (including 8.x)
+
+## Development
+
+```bash
+bin/setup          # Install dependencies
+bundle exec rake   # Run tests + linting (RSpec + Standard)
+bin/console        # Interactive prompt
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome at [github.com/amberpixels/railbow](https://github.com/amberpixels/railbow).
+
+## License
+
+MIT License. See [LICENSE.txt](https://github.com/amberpixels/railbow/blob/main/LICENSE.txt).

data/exe/railbow

@@ -0,0 +1,110 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/railbow/version"
+require_relative "../lib/railbow/logo"
+
+module Railbow
+  module CLI
+    module_function
+
+    def run(args)
+      case args.first
+      when "--help", "-h", nil
+        Railbow.print_logo
+        puts
+        print_usage
+        exit 0
+      when "--version", "-v"
+        Railbow.print_logo
+        puts " v#{Railbow::VERSION}"
+        exit 0
+      when "init"
+        require "railbow/init"
+        Railbow::Init.run
+        exit 0
+      when "demo"
+        require_relative "../lib/railbow/demo/runner"
+        Railbow::Demo::Runner.run(args[1] || "status")
+        exit 0
+      end
+
+      project_gemfile = find_gemfile
+      unless project_gemfile
+        warn "Error: Could not find a Gemfile in the current directory or any parent directory."
+        exit 1
+      end
+
+      wrapper_path = create_wrapper_gemfile(project_gemfile)
+      symlink_lockfile(project_gemfile, wrapper_path)
+
+      env = {"BUNDLE_GEMFILE" => wrapper_path}
+      Kernel.exec(env, "bundle", "exec", *args)
+    end
+
+    def find_gemfile
+      dir = Dir.pwd
+      loop do
+        gemfile = File.join(dir, "Gemfile")
+        return gemfile if File.exist?(gemfile)
+
+        parent = File.dirname(dir)
+        return nil if parent == dir
+
+        dir = parent
+      end
+    end
+
+    def create_wrapper_gemfile(project_gemfile)
+      require "tempfile"
+
+      wrapper = Tempfile.new(["railbow-wrapper-", ".gemfile"], "/tmp")
+      wrapper.write(<<~RUBY)
+        eval_gemfile #{project_gemfile.inspect}
+        gem "railbow", "= #{Railbow::VERSION}"
+      RUBY
+      wrapper.close
+
+      wrapper.path
+    end
+
+    def symlink_lockfile(project_gemfile, wrapper_path)
+      lockfile = "#{project_gemfile}.lock"
+      return unless File.exist?(lockfile)
+
+      wrapper_lock = "#{wrapper_path}.lock"
+      File.symlink(lockfile, wrapper_lock)
+    end
+
+    def print_usage
+      puts <<~HELP
+        Usage: railbow <command> [args...]
+
+        Wraps any bundled Rails command so railbow is loaded automatically,
+        without modifying the project's Gemfile.
+
+        Commands:
+          init             Generate a config file (interactive)
+          demo [type]      See railbow in action without a Rails project
+                           Types: status (default), migrate, routes, all
+
+        Examples:
+          railbow demo
+          railbow demo routes
+          railbow init
+          railbow rake db:migrate:status
+          railbow rails db:migrate:status
+          railbow rake db:migrate
+
+        Options:
+          --help, -h       Show this help message
+          --version, -v    Show version
+
+        For daily use, add railbow to your Gemfile instead:
+          gem "railbow", group: :development
+      HELP
+    end
+  end
+end
+
+Railbow::CLI.run(ARGV)

data/lib/railbow/about_formatter.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "formatters/base"
+require_relative "config"
+require_relative "table"
+
+module Railbow
+  module AboutFormatter
+    def to_s
+      return super if Railbow.plain?
+
+      formatter = Formatters::Base.new
+
+      columns = [
+        Table::Column.new(label: "Property", sticky: true),
+        Table::Column.new(label: "Value")
+      ]
+
+      rows = @@properties.map do |(name, value)|
+        val = value.respond_to?(:call) ? value.call : value
+        [formatter.bold(name), val.to_s]
+      end
+
+      renderer = Table::Renderer.new(
+        columns: columns,
+        theme: Table::Themes::PLAIN,
+        compact: Railbow::Params.compact_options,
+        aliases: Railbow::Config.table_aliases
+      )
+
+      output = +"\n"
+      output << renderer.render(rows)
+      output << "\n"
+      output
+    end
+  end
+end

data/lib/railbow/color_assigner.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Railbow
+  # Assigns maximally-spaced colors to a set of unique labels.
+  #
+  # Instead of hashing into a fixed palette (where two labels can collide
+  # onto adjacent colors), this assigns colors by rank — evenly spacing
+  # hues around the color wheel. Two labels always get maximally different
+  # colors, three labels get ~120 deg apart, etc.
+  #
+  # Usage:
+  #   assigner = Railbow::ColorAssigner.new(["Alice", "Bob", "Carol"])
+  #   assigner.color_for("Alice")  # => "\e[38;5;174m"
+  #   assigner.code_for("Bob")     # => 116  (256-color code)
+  #
+  class ColorAssigner
+    # Soft/muted 256-color codes arranged around the hue wheel.
+    # 12 stops, evenly spaced in hue, all at moderate saturation/lightness
+    # so they look pleasant on dark terminals.
+    WHEEL = [
+      174, # 0°   coral / muted rose
+      216, # 30°  peach
+      180, # 60°  warm sand
+      150, # 120° sage green
+      116, # 160° soft teal
+      117, # 200° soft sky blue
+      111, # 220° periwinkle
+      146, # 260° lavender
+      176, # 300° soft magenta
+      182  # 330° dusty pink
+    ].freeze
+
+    def initialize(labels)
+      sorted = labels.uniq.sort
+      @mapping = {}
+      sorted.each_with_index do |label, idx|
+        wheel_idx = (idx * WHEEL.size / [sorted.size, 1].max) % WHEEL.size
+        @mapping[label] = WHEEL[wheel_idx]
+      end
+    end
+
+    # Returns the 256-color ANSI escape for the given label.
+    def color_for(label)
+      code = code_for(label)
+      "\e[38;5;#{code}m"
+    end
+
+    # Returns just the 256-color code integer for the given label.
+    def code_for(label)
+      @mapping[label] || WHEEL[0]
+    end
+  end
+end

data/lib/railbow/config.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Railbow
+  module Config
+    GEM_DEFAULTS = {
+      "aliases" => {
+        "columns" => {
+          "Status" => "Live"
+        },
+        "values" => {
+          "Status" => {"up" => "↑↑", "down" => "↓↓"}
+        }
+      },
+      "since" => "70d",
+      "git" => "author:all,diff,mask:auto",
+      "author_format" => "short",
+      "view" => "calendar,tables",
+      "calendar" => "wticks"
+    }.freeze
+
+    @root = nil
+    @loaded = nil
+
+    module_function
+
+    # Overridable root for config file lookup. Defaults to Rails.root or Dir.pwd.
+    def root
+      @root || ((defined?(Rails) && Rails.respond_to?(:root) && Rails.root) ? Rails.root.to_s : Dir.pwd)
+    end
+
+    def root=(path)
+      @root = path
+      @loaded = nil
+    end
+
+    def reset!
+      @root = nil
+      @loaded = nil
+    end
+
+    def global_dir
+      xdg = ENV["XDG_CONFIG_HOME"]
+      base = (xdg && !xdg.empty?) ? xdg : File.join(Dir.home, ".config")
+      File.join(base, "railbow")
+    end
+
+    def config_files
+      files = []
+
+      # 1. Global
+      global = File.join(global_dir, "config.yml")
+      files << global if File.exist?(global)
+
+      # 2. Project .railbow.yml / .railbow.yaml
+      %w[.railbow.yml .railbow.yaml].each do |name|
+        full = File.join(root, name)
+        if File.exist?(full)
+          files << full
+          break
+        end
+      end
+
+      # 3. Local .railbow.local.yml / .railbow.local.yaml
+      %w[.railbow.local.yml .railbow.local.yaml].each do |name|
+        full = File.join(root, name)
+        if File.exist?(full)
+          files << full
+          break
+        end
+      end
+
+      files
+    end
+
+    def load
+      @loaded ||= config_files.reduce(GEM_DEFAULTS.dup) { |acc, path| deep_merge(acc, read_yaml(path)) }
+    end
+
+    def column_aliases
+      load.dig("aliases", "columns") || {}
+    end
+
+    def value_aliases
+      load.dig("aliases", "values") || {}
+    end
+
+    def table_aliases
+      {columns: column_aliases, values: value_aliases}
+    end
+
+    def read_yaml(path)
+      content = begin
+        YAML.safe_load_file(path)
+      rescue Psych::SyntaxError, Psych::DisallowedClass
+        warn "  Warning: failed to parse #{path}, using defaults"
+        {}
+      end
+      content.is_a?(Hash) ? content : {}
+    end
+
+    def deep_merge(base, override)
+      base.merge(override) do |_key, old_val, new_val|
+        if old_val.is_a?(Hash) && new_val.is_a?(Hash)
+          deep_merge(old_val, new_val)
+        else
+          new_val
+        end
+      end
+    end
+  end
+end