schema_reaper 1.0.8 → 1.0.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c46503b5869a825db2f07b26cb2c8593149d36ec937f4f942ad7429c3bd33c03
-  data.tar.gz: 6bc513d41c987266464a1cc66bc34ae50a483ef37daf3751d3051fb34f46d032
+  metadata.gz: e86ae3d2cb33da4bdf545809519f27fb5104e73f4996bb650e2fd3d3f9232067
+  data.tar.gz: fa0faef4c064a923bd2d699d6fbc3b58d364f7d94a3a0cf67efc93e86ec889b1
 SHA512:
-  metadata.gz: 6f43c6e3dc588b49d4bdfc2ee0c3baa95d08db6494a0c2f255585c7d1e3521f3db942bfcb1ff0e9197fc46acad98f2ccb14903c6686534bd4562ae8ad9bbb467
-  data.tar.gz: 44b21854388bb1fb230c0edc9728c37c5c23137953fa30768425a95257ad15ddb676c582d1e6565d62d77777bab1182c6aa561acc77b6d24839635ded463c1c1
+  metadata.gz: 4a49eb0d8ff830df84543e945ae809af391f86fc3259cf69d3189a5c60eff90478d59b2bf914af7eed57104f924ed1034c26b94eabd662e8d5a73192e44b38b1
+  data.tar.gz: f83a196f89bda5b52ce31598c80e4300e6816b93519e810b60febaa588647a4d3432b049567baff48482d2ab362226581a02a918284fc823a0bcccebb828604c

data/CHANGELOG.md

@@ -1,5 +1,48 @@
 # Changelog
 
+## [1.0.9] - 2026-09-09
+
+### Added
+- Automatic database connection in a Rails app. If `database_url:` is not set in
+  `.schema_reaper.yml` and `DATABASE_URL` is not in the environment,
+  schema_reaper now reads `config/database.yml` — rendering ERB, resolving YAML
+  aliases, honouring `SCHEMA_REAPER_ENV` / `RAILS_ENV` (default `development`),
+  and handling Rails 6+ multi-database sections. `bundle exec schema_reaper
+  scan` works with no setup. PostgreSQL adapters only.
+- Connection and missing-config errors now print a one-line `✗` message
+  instead of a Ruby backtrace.
+
+### Fixed
+- `pg_class.reltuples` is `-1` on PostgreSQL 14+ for a table that has never
+  been analysed. It was being treated as a real row count: `dead_table`
+  printed "table holds ~-1 row(s)", scored it at the 0.4 "non-empty" level,
+  and the reclaimable-bytes estimate went negative. A negative `reltuples` is
+  now mapped to "unknown" — the finding drops to 0.5 confidence, the evidence
+  says the count is unknown and suggests running `ANALYZE`, and the byte
+  estimate stays at 0. Found by running against a real production schema.
+
+### Changed
+- Redesigned the terminal report (`scan` / `scan --format table`):
+  - one summary line (finding count + total reclaimable),
+  - findings grouped under their table, sorted by confidence,
+  - a five-cell confidence bar with the percentage, padded severity and
+    analyzer name, the target column/index, and the reclaimable size,
+  - evidence on one dim `·`-joined line, the fix on a green `→` line,
+  - a footer with a severity tally and a per-analyzer breakdown.
+- Colour is automatic on an interactive terminal and suppressed when output
+  is piped or `NO_COLOR` is set. New `scan --color` / `--no-color` to force it.
+- JSON, SARIF and Markdown reporters are unchanged.
+- `trend` now prints a readable progress block — finding count and reclaimable
+  total with signed deltas since the first and previous run, a list of findings
+  newly introduced and resolved, and the snapshot dates — instead of a raw
+  `pp` hash dump.
+- `baseline` and `generate-migration` print a short titled block with a `✓`
+  line and next steps; `generate-migration` spells out the two-step deploy.
+- `scan --ci` reports new findings as a `✗` block on stderr with the finding
+  ids indented under it.
+- The "unused_index skipped / no query history" message is now a single
+  formatted `!` notice on stderr.
+
 ## [1.0.8] - 2026-09-04
 
 ### Fixed

data/README.md

@@ -21,23 +21,55 @@ gem "schema_reaper", group: :development
 bundle install
 ```
 
-Requires Ruby >= 3.1 and PostgreSQL. The database connection resolves from
-`database_url` in `.schema_reaper.yml`, else `ENV["DATABASE_URL"]`.
+Requires Ruby >= 2.7 and PostgreSQL. The database connection is resolved in
+this order:
+
+1. `database_url:` in `.schema_reaper.yml`
+2. `ENV["DATABASE_URL"]`
+3. `config/database.yml` for the current environment (`SCHEMA_REAPER_ENV` /
+   `RAILS_ENV`, default `development`) — ERB and YAML aliases are handled, as
+   are Rails 6+ multi-database sections
+
+So in a Rails app, `bundle exec schema_reaper scan` works with no setup.
 
 ## Usage
 
 ```
-bundle exec schema_reaper scan                    # human-readable report
+bundle exec schema_reaper scan                    # grouped terminal report
 bundle exec schema_reaper scan --format markdown  # PR-comment table
 bundle exec schema_reaper scan --format sarif     # GitHub code scanning
 bundle exec schema_reaper scan --format json
 bundle exec schema_reaper scan --ci               # exit 1 on new findings
 bundle exec schema_reaper scan --min-confidence 0.8
+bundle exec schema_reaper scan --no-color         # force plain output
 bundle exec schema_reaper baseline                # accept current findings
 bundle exec schema_reaper trend                   # snapshot + progress delta
 bundle exec schema_reaper generate-migration users legacy_api_token
 ```
 
+The `scan` report groups findings by table and sorts by confidence:
+
+```
+  schema_reaper  5 findings  ~93.8 KB reclaimable
+
+  users
+    █████  90%  medium  missing_fk_index     team_id
+           team_id is a foreign key with no covering index
+           → add_index :users, :team_id
+    ████░  85%  high    always_null_column   api_key  46.9 KB
+           pg_stats.null_frac = 1.0 across ~3000 row(s) · column carries no data
+           → verify with `SELECT count(api_key) FROM users` then stage a removal
+
+  stale_exports
+    ████░  85%  high    dead_table
+           no model or query reference · table holds ~0 row(s)
+           → confirm no external consumer, then `drop_table :stale_exports`
+
+  high 2   medium 1   low 2
+```
+
+Colour is automatic on a terminal, off when piped or `NO_COLOR` is set.
+
 In a Rails app the railtie also gives you
 `rake schema_reaper:scan|baseline|trend` (with `FORMAT=`).
 

data/RELEASE_CHECKLIST.md

@@ -0,0 +1,218 @@
+# Release checklist
+
+Run top to bottom for every release. Nothing here is optional — each item has
+burned us at least once.
+
+---
+
+## 1. History & attribution hygiene
+
+Do this **before** committing, and again before force-pushing anything.
+
+- [ ] **No AI / wrong-author trailers.** Commit messages must not contain
+      `Co-Authored-By: Claude`, `Claude-Session:`, or any `Co-Authored-By` for
+      someone who did not write the change.
+
+  ```sh
+  git log --all --format='%B' | grep -iE 'co-authored|claude-session|claude' && echo "DIRTY" || echo "clean"
+  ```
+
+- [ ] **Authors are only the real people.** Expect `aksshatt` and `mitkush`
+      only (GitHub's merge-commit `GitHub <noreply@github.com>` committer is
+      fine).
+
+  ```sh
+  git log --all --format='%an <%ae>%n%cn <%ce>' | sort -u
+  ```
+
+- [ ] **Working tree identity is right** (so new commits are attributed
+      correctly):
+
+  ```sh
+  git config user.name   # aksshatt
+  git config user.email  # akshatpegwar5@gmail.com
+  ```
+
+- [ ] If a bad trailer or author already landed: strip it, then force-push
+      `main` **and** move the affected tag.
+
+  ```sh
+  FILTER_BRANCH_SQUELCH_WARNING=1 git filter-branch -f \
+    --msg-filter 'grep -v -iE "^(Co-Authored-By: Claude|Claude-Session:)"' \
+    --tag-name-filter cat -- <range>
+  git tag -f -a vX.Y.Z -m "schema_reaper X.Y.Z"
+  git push --force <remote> main
+  git push --force <remote> refs/tags/vX.Y.Z
+  ```
+
+- [ ] After any force-push, re-verify with a **fresh full clone** (not
+      `--depth 1` — shallow only checks HEAD):
+
+  ```sh
+  git clone <url> /tmp/verify && cd /tmp/verify
+  git log --all --format='%an <%ae>' | sort -u
+  git log --all --format='%B' | grep -iE 'claude|rahul' || echo clean
+  ```
+
+---
+
+## 2. Code checks
+
+- [ ] Full CI locally — must be **0 failures**, **no offenses**:
+
+  ```sh
+  bundle exec rake          # rspec + rubocop
+  ```
+
+- [ ] **Ruby 2.7 floor holds** (the gem supports `>= 2.7`; endless methods and
+      3.0+ syntax are a syntax error there):
+
+  ```sh
+  for f in $(find lib spec exe -name '*.rb'); do ruby2.7 -c "$f" >/dev/null || echo "FAIL $f"; done
+  ```
+
+  RuboCop's `TargetRubyVersion: 2.7` also catches this via `Lint/Syntax`.
+
+- [ ] `gem build schema_reaper.gemspec` — **no warnings**, correct version.
+
+- [ ] Packaged file list is complete (every `lib/**` file present):
+
+  ```sh
+  tar -xf schema_reaper-X.Y.Z.gem -C /tmp/g && tar -tzf /tmp/g/data.tar.gz | grep '^lib/'
+  ```
+
+---
+
+## 3. Live database smoke test
+
+Static-only unit specs do not exercise the real introspection SQL. Run against
+a throwaway PostgreSQL with a deliberately dirty schema.
+
+- [ ] Seed a DB with: a dead column, an always-NULL FK column, a single-value
+      column, a dead (0-row) table, a composite-PK table, a polymorphic
+      `(_type, _id)` pair, a duplicate/prefix index, an unindexed FK **that has
+      data**.
+
+- [ ] Run every command and eyeball the output:
+
+  ```sh
+  schema_reaper scan                     # grouped report, no duplicate rows per column/index
+  schema_reaper scan --format json  | ruby -rjson -e 'JSON.parse(STDIN.read)'   # valid
+  schema_reaper scan --format sarif | ruby -rjson -e 'p JSON.parse(STDIN.read)["version"]'  # "2.1.0"
+  schema_reaper scan --format markdown
+  schema_reaper scan --no-color          # plain output, no ANSI
+  schema_reaper baseline && schema_reaper scan --ci ; echo $?   # 0 when nothing new
+  # add a dead column, then:
+  schema_reaper scan --ci ; echo $?      # 1, names the new finding
+  schema_reaper generate-migration <table> <col>   # two files, both `ruby -c` clean
+  schema_reaper trend
+  ```
+
+- [ ] Assertions that have regressed before:
+  - `missing_fk_index` does **not** suggest `add_index` on an always-NULL column.
+  - polymorphic `*_id` is **not** flagged when a `(*_type, *_id)` index exists.
+  - `unused_index` **skips** (with a stderr notice) when the DB has no query
+    history — it does not flag every index.
+  - a finding for one physical column/index appears **once** (highest
+    confidence wins; others listed as `also flagged by:`).
+  - `--format json` on stdout is clean JSON — the `unused_index` notice is on
+    **stderr**.
+
+- [ ] Live introspection spec:
+
+  ```sh
+  SCHEMA_REAPER_TEST_DATABASE_URL=postgres:///throwaway bundle exec rspec spec/introspect/postgres_spec.rb
+  ```
+
+- [ ] `dropdb` the throwaway database.
+
+---
+
+## 4. Version & changelog
+
+- [ ] Bump `lib/schema_reaper/version.rb`.
+- [ ] `CHANGELOG.md` — new dated section, **Fixed / Changed / Added**, credit
+      PRs and their authors.
+- [ ] README still accurate (Ruby floor, flags, sample output, analyzer list).
+
+---
+
+## 5. Commit, tag, push
+
+- [ ] Commit message: plain, no AI trailer (see §1).
+- [ ] Annotated tag `vX.Y.Z`.
+
+  ```sh
+  git tag -a vX.Y.Z -m "schema_reaper X.Y.Z"
+  git push <remote> main
+  git push <remote> refs/tags/vX.Y.Z
+  ```
+
+---
+
+## 6. Publish the gem
+
+RubyGems requires account MFA; `gem push` prompts for an OTP that only the
+maintainer can enter.
+
+```sh
+gem build schema_reaper.gemspec
+gem push schema_reaper-X.Y.Z.gem --otp <6-digit code>
+```
+
+- [ ] Confirm it went live (API cache lags ~1 min):
+
+  ```sh
+  curl -s https://rubygems.org/api/v1/gems/schema_reaper.json \
+    | ruby -rjson -e 'd=JSON.parse(STDIN.read); puts "#{d["version"]} #{d["authors"]}"'
+  ```
+
+- [ ] Published versions are **immutable**. A metadata/description typo needs a
+      new version — never assume you can edit a live one.
+
+---
+
+## 7. Post-publish
+
+- [ ] **Clean-room install** from RubyGems (not the local checkout):
+
+  ```sh
+  gem install schema_reaper -v X.Y.Z --install-dir /tmp/cr --no-document
+  GEM_HOME=/tmp/cr /tmp/cr/bin/schema_reaper version
+  # then run §3 against a live DB using that binary
+  ```
+
+- [ ] **Contributors graph.** GitHub's sidebar/Insights widget caches hard and
+      can lag ~24h behind the real data. The source of truth is:
+
+  ```sh
+  gh api repos/aksshatt/schema_reaper/contributors --jq '.[].login'
+  ```
+
+  If the widget still shows a removed name after the API is clean: it is stale
+  cache of force-pushed-away commits, clears on GitHub's next `gc`. A brand-new
+  repo populated by `git push --mirror` of the clean history never shows the
+  ghost.
+
+- [ ] Rotate any personal access token that was pasted into a chat/log.
+
+---
+
+## Repo-move runbook (only when starting a fresh repo to shed a cache)
+
+```sh
+git clone --bare <old-url> /tmp/bare          # --bare, not --mirror: skips refs/pull/*
+git -C /tmp/bare branch -D <stale/pr-branches>
+gh api --method PATCH repos/aksshatt/schema_reaper -f name=schema_reaper_old
+gh repo create aksshatt/schema_reaper --public --description "<desc>"
+git -C /tmp/bare push --mirror https://<user>:<token>@github.com/aksshatt/schema_reaper.git
+gh api --method PUT repos/aksshatt/schema_reaper/collaborators/mitkush -f permission=push
+gh api --method PATCH repos/aksshatt/schema_reaper -f has_issues=true -f has_wiki=true -f has_projects=true
+gh api --method PATCH repos/aksshatt/schema_reaper_old -F archived=true
+git remote set-url origin https://github.com/aksshatt/schema_reaper.git
+```
+
+`push --mirror` copies commit objects **byte-for-byte** — authors, dates and
+SHAs are unchanged. It carries branches, tags and deletions; it does **not**
+carry issues, PRs, stars, releases text, settings, webhooks or the wiki. Set
+those manually on the new repo.

data/lib/schema_reaper/analyzers/dead_table.rb

@@ -76,7 +76,11 @@ module SchemaReaper
       def evidence_for(table)
         ev = ["no model or query reference to `#{table.name}` in scanned code"]
         ev << "runtime data shows no access" if runtime.present?
-        ev << "table holds ~#{table.row_count} row(s)" unless table.row_count.nil?
+        ev << if table.row_count.nil?
+                "row count unknown — run ANALYZE for a confidence boost"
+              else
+                "table holds ~#{table.row_count} row(s)"
+              end
         ev
       end
 

data/lib/schema_reaper/cli.rb

@@ -21,9 +21,11 @@ module SchemaReaper
     option :record, type: :boolean, default: false,
                     desc: "append this run to the history log"
     option :min_confidence, type: :numeric, default: 0.0
+    option :color, type: :boolean, default: nil,
+                   desc: "force colour on/off for the table report (default: auto)"
     def scan
       findings = run.select { |f| f.confidence >= options[:min_confidence] }
-      SchemaReaper.reporter(options[:format]).new(findings).render
+      render_report(findings)
 
       History.new(config.history_log).record(findings) if options[:record]
       enforce_baseline(findings) if options[:ci]
@@ -33,20 +35,31 @@ module SchemaReaper
     def baseline
       findings = run
       Baseline.new(config.baseline_path).write(findings)
-      say "wrote #{findings.size} finding(s) to #{config.baseline_path}"
+      console.title("baseline")
+      console.ok("recorded #{findings.size} finding#{"s" unless findings.size == 1} " \
+                 "as the accepted baseline")
+      console.info("file: #{config.baseline_path}")
+      console.info("`scan --ci` now fails only on findings that appear after this point.")
     end
 
     desc "trend", "Append a snapshot and print progress over time"
     def trend
-      History.new(config.history_log).record(run)
-      require "pp"
-      pp History.new(config.history_log).trend
+      history = History.new(config.history_log)
+      history.record(run)
+      Reporters::Trend.new(history.trend, color: options[:color]).render
     end
 
     desc "generate-migration TABLE COLUMN", "Emit a staged removal migration pair"
     def generate_migration(table, column)
-      MigrationGenerator.new(table: table, column: column).call
-                        .each { |p| say "created #{p}" }
+      paths = MigrationGenerator.new(table: table, column: column).call
+      console.title("generate-migration", "#{table}.#{column}")
+      console.ok("created two migrations:")
+      paths.each { |p| console.info("  #{p}") }
+      console.blank
+      console.list("next:", [
+                     "deploy step 1 (adds `#{column}` to ignored_columns) and let it soak",
+                     "run step 2 (`remove_column`) only once nothing has broken"
+                   ])
     end
 
     desc "version", "Print version"
@@ -62,14 +75,31 @@ module SchemaReaper
 
     def run
       Runner.new(config: config).run
+    rescue SchemaReaper::Error => e
+      console.problem(e.message)
+      exit 1
+    end
+
+    def render_report(findings)
+      if options[:format] == "table"
+        Reporters::Table.new(findings, color: options[:color]).render
+      else
+        SchemaReaper.reporter(options[:format]).new(findings).render
+      end
+    end
+
+    def console
+      @console ||= Reporters::Console.new(color: options[:color])
     end
 
     def enforce_baseline(findings)
       new_ones = Baseline.new(config.baseline_path).new_among(findings)
       return if new_ones.empty?
 
-      warn "schema_reaper: #{new_ones.size} new finding(s) since baseline"
-      new_ones.each { |f| warn "  - #{f.id}" }
+      console.problem(
+        "#{new_ones.size} new finding#{"s" unless new_ones.size == 1} since the baseline",
+        items: new_ones.map(&:id)
+      )
       exit 1
     end
   end

data/lib/schema_reaper/config.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "yaml"
+require_relative "database_url"
 
 module SchemaReaper
   # Loaded from .schema_reaper.yml at the project root. Every key has a default
@@ -22,12 +23,13 @@ module SchemaReaper
       "runtime_log" => ".schema_reaper/runtime.jsonl",
       "history_log" => ".schema_reaper/history.jsonl",
       "baseline" => ".schema_reaper/baseline.json",
+      "database_yml" => "config/database.yml", # Rails fallback for the connection
       "require" => [] # extra files to load (custom analyzers)
     }.freeze
 
     def self.load(path = ".schema_reaper.yml")
       raw = File.exist?(path) ? (YAML.safe_load_file(path) || {}) : {}
-      new(deep_merge(DEFAULTS, raw))
+      new(deep_merge(DEFAULTS, raw), root: File.dirname(File.expand_path(path)))
     end
 
     def self.deep_merge(base, override)
@@ -36,12 +38,19 @@ module SchemaReaper
       end
     end
 
-    def initialize(data)
+    def initialize(data, root: Dir.pwd)
       @data = data
+      @root = root
     end
 
+    # Resolution order:
+    #   1. database_url: in .schema_reaper.yml
+    #   2. ENV["DATABASE_URL"]
+    #   3. config/database.yml for the current environment (Rails apps)
     def database_url
-      @data["database_url"] || ENV.fetch("DATABASE_URL", nil)
+      @data["database_url"] ||
+        ENV.fetch("DATABASE_URL", nil) ||
+        DatabaseUrl.from_rails(root: @root, path: @data["database_yml"])
     end
 
     def scan_paths

data/lib/schema_reaper/database_url.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "erb"
+
+module SchemaReaper
+  # Best-effort resolution of a PostgreSQL connection URL from a Rails project,
+  # so `schema_reaper scan` works in an app without `DATABASE_URL` exported or a
+  # `database_url:` in .schema_reaper.yml.
+  #
+  # Order of preference is applied by Config; this module only handles the
+  # config/database.yml case.
+  module DatabaseUrl
+    module_function
+
+    POSTGRES_ADAPTERS = %w[postgresql postgis postgres].freeze
+
+    # @return [String, nil]
+    def from_rails(root: Dir.pwd, path: "config/database.yml", env: nil)
+      file = File.expand_path(path, root)
+      return nil unless File.file?(file)
+
+      section = section_for(load_yaml(file), env || rails_env)
+      return nil unless section.is_a?(Hash)
+
+      section["url"] || build_url(section)
+    rescue StandardError
+      nil
+    end
+
+    def rails_env
+      ENV["SCHEMA_REAPER_ENV"] || ENV["RAILS_ENV"] || ENV["RACK_ENV"] || "development"
+    end
+
+    def load_yaml(file)
+      rendered = ERB.new(File.read(file)).result
+      begin
+        YAML.safe_load(rendered, aliases: true)
+      rescue ArgumentError # older Psych without the aliases: kwarg
+        YAML.safe_load(rendered, [], [], true)
+      end
+    rescue StandardError
+      YAML.load_file(file)
+    end
+
+    # Rails 6+ allows `development: { primary: {...}, replica: {...} }`. Pick the
+    # primary, or the first sub-config, when the env section is nested.
+    def section_for(data, env)
+      return nil unless data.is_a?(Hash)
+
+      section = data[env] || data[env.to_s]
+      return section unless nested?(section)
+
+      section["primary"] || section.values.find { |v| v.is_a?(Hash) }
+    end
+
+    def nested?(section)
+      section.is_a?(Hash) &&
+        !section.key?("adapter") && !section.key?("url") && !section.key?("database") &&
+        section.values.any?(Hash)
+    end
+
+    def build_url(section)
+      adapter = section["adapter"].to_s
+      return nil unless POSTGRES_ADAPTERS.include?(adapter)
+
+      db = section["database"]
+      return nil if db.to_s.empty?
+
+      userinfo = [section["username"], section["password"]].compact.join(":")
+      host = section["host"].to_s
+      hostport = host.empty? ? "" : "#{host}#{":#{section["port"]}" if section["port"]}"
+      auth = userinfo.empty? ? "" : "#{userinfo}@"
+
+      "postgresql://#{auth}#{hostport}/#{db}"
+    end
+  end
+end

data/lib/schema_reaper/finding.rb

@@ -36,6 +36,14 @@ module SchemaReaper
       self[:reclaimable_bytes] || 0
     end
 
+    # Column and/or index this finding points at, without the table name
+    # (callers that group by table already show it). nil for a whole-table
+    # finding.
+    def target_label
+      parts = [column, index].compact
+      parts.empty? ? nil : parts.join(" · ")
+    end
+
     def to_h
       super.merge(id: id, reclaimable_bytes: reclaimable_bytes)
     end

data/lib/schema_reaper/history.rb

@@ -49,6 +49,8 @@ module SchemaReaper
         snapshots: snaps.size,
         first_at: first.at,
         last_at: last.at,
+        latest_count: last.count,
+        latest_bytes: last.reclaimable_bytes,
         count_change_total: last.count - first.count,
         count_change_last: last.count - prev.count,
         newly_introduced: (last.ids - prev.ids),

data/lib/schema_reaper/introspect/postgres.rb

@@ -12,11 +12,17 @@ module SchemaReaper
         "timestamp with time zone" => 8, "uuid" => 16
       }.freeze
 
+      NO_URL = "no database connection found. schema_reaper looks, in order, for: " \
+               "database_url: in .schema_reaper.yml; the DATABASE_URL env var; " \
+               "config/database.yml for RAILS_ENV (default: development, Postgres only)."
+
       def initialize(url)
-        raise Error, "no database_url configured" if url.nil? || url.empty?
+        require "pg" # load first so the PG::Error rescue below can resolve
+        raise Error, NO_URL if url.nil? || url.empty?
 
-        require "pg"
         @conn = PG.connect(url)
+      rescue PG::Error => e
+        raise Error, "could not connect to the database: #{e.message.strip}"
       end
 
       def call
@@ -140,10 +146,17 @@ module SchemaReaper
         SQL
       end
 
+      # pg_class.reltuples is an estimate maintained by ANALYZE/VACUUM. On
+      # PostgreSQL 14+ it is -1 for a relation that has never been analysed,
+      # which is "unknown", not "minus one row". Map anything negative to nil so
+      # analyzers treat the count as unavailable.
       def row_count_for(table)
-        exec(<<~SQL, [table]).first&.fetch("reltuples")&.to_f&.round
+        raw = exec(<<~SQL, [table]).first&.fetch("reltuples")&.to_f
           SELECT reltuples FROM pg_class WHERE relname = $1
         SQL
+        return nil if raw.nil? || raw.negative?
+
+        raw.round
       end
 
       def exec(sql, params = nil)

data/lib/schema_reaper/reporters/ansi.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module SchemaReaper
+  module Reporters
+    # Minimal ANSI styling. Colour is emitted only for an interactive terminal
+    # and stays off when NO_COLOR is set, when output is redirected, or when
+    # the caller forces it off.
+    class Ansi
+      CODES = {
+        reset: 0, bold: 1, dim: 2,
+        red: 31, green: 32, yellow: 33, blue: 34, magenta: 35, cyan: 36, grey: 90
+      }.freeze
+
+      SEVERITY_COLOUR = { high: :red, medium: :yellow, low: :cyan }.freeze
+
+      def initialize(io: $stdout, enabled: nil)
+        @on = enabled.nil? ? auto?(io) : enabled
+      end
+
+      def on?
+        @on
+      end
+
+      # paint(:bold, :red) { "text" } or paint("text", :bold, :red)
+      def paint(text, *styles)
+        return text unless @on && !styles.empty?
+
+        seq = styles.filter_map { |s| CODES[s] }.join(";")
+        "\e[#{seq}m#{text}\e[0m"
+      end
+
+      def severity(sev, text = sev.to_s)
+        paint(text, :bold, SEVERITY_COLOUR.fetch(sev, :grey))
+      end
+
+      # A five-cell bar for a 0.0..1.0 value, coloured by severity.
+      def confidence_bar(value, sev)
+        filled = (value * 5).round.clamp(0, 5)
+        bar = ("█" * filled) + ("░" * (5 - filled))
+        paint(bar, SEVERITY_COLOUR.fetch(sev, :grey))
+      end
+
+      private
+
+      def auto?(io)
+        return false if ENV["NO_COLOR"] && !ENV["NO_COLOR"].empty?
+        return false unless io.respond_to?(:tty?) && io.tty?
+
+        true
+      end
+    end
+  end
+end

data/lib/schema_reaper/reporters/console.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require_relative "ansi"
+
+module SchemaReaper
+  module Reporters
+    # Shared styling for the CLI's short command output (baseline, trend,
+    # generate-migration, the CI gate and stderr notices). Keeps every command
+    # looking like it belongs to the same tool.
+    class Console
+      def initialize(out: $stdout, err: $stderr, color: nil)
+        @out = out
+        @err = err
+        @a = Ansi.new(io: out, enabled: color)
+        @ae = Ansi.new(io: err, enabled: color)
+      end
+
+      def blank
+        @out.puts
+      end
+
+      # "  schema_reaper trend  ·  3 snapshots"
+      def title(command, meta = nil)
+        line = "  #{@a.paint("schema_reaper", :bold)} #{@a.paint(command, :bold)}"
+        line << "  #{@a.paint("·  #{meta}", :dim)}" if meta
+        @out.puts
+        @out.puts line
+        @out.puts
+      end
+
+      def ok(message)
+        @out.puts "  #{@a.paint("✓", :green, :bold)} #{message}"
+      end
+
+      def info(message)
+        @out.puts "  #{message}"
+      end
+
+      # aligned "label   value  (aside)" row
+      def row(label, value, aside = nil)
+        text = format("  %-15s %s", label, @a.paint(value.to_s, :bold))
+        text << "  #{@a.paint("(#{aside})", :dim)}" if aside && !aside.empty?
+        @out.puts text
+      end
+
+      def list(heading, items, colour: :dim)
+        return if items.empty?
+
+        @out.puts "  #{@a.paint(heading, colour)}" if heading && !heading.empty?
+        items.each { |i| @out.puts "    #{@a.paint("- #{i}", colour)}" }
+      end
+
+      # A single stderr notice, e.g. the unused-index skip.
+      def notice(message)
+        @err.puts "  #{@ae.paint("!", :yellow, :bold)} #{message}"
+      end
+
+      def problem(message, items: [])
+        @err.puts
+        @err.puts "  #{@ae.paint("✗", :red, :bold)} #{@ae.paint(message, :bold)}"
+        items.each { |i| @err.puts "    #{@ae.paint("- #{i}", :red)}" }
+      end
+    end
+  end
+end

data/lib/schema_reaper/reporters/table.rb

@@ -1,42 +1,100 @@
 # frozen_string_literal: true
 
 require_relative "bytes"
+require_relative "ansi"
 
 module SchemaReaper
   module Reporters
-    # Human-readable terminal output, sorted by confidence then severity.
+    # Human-readable terminal report: a summary line, findings grouped by table
+    # and sorted by confidence, then a severity/type tally. Colour is used only
+    # on an interactive terminal (see Ansi).
     class Table
       SEV_ORDER = { high: 0, medium: 1, low: 2 }.freeze
 
-      def initialize(findings, io: $stdout)
+      def initialize(findings, io: $stdout, color: nil)
         @findings = findings
         @io = io
+        @a = Ansi.new(io: io, enabled: color)
       end
 
       def render
-        if @findings.empty?
-          @io.puts "schema_reaper: no findings. Schema is lean."
-          return
-        end
+        return render_clean if @findings.empty?
 
-        sorted.each { |f| render_finding(f) }
-        @io.puts
-        @io.puts "#{@findings.size} finding(s). " \
-                 "~#{Bytes.human(total_reclaimable)} reclaimable."
+        header
+        grouped.each { |table, group| render_table(table, group) }
+        footer
       end
 
       private
 
-      def render_finding(f)
-        target = [f.table, f.column, f.index].compact.join(".")
-        @io.puts format("[%-6s %3d%%] %-14s %s",
-                        f.severity, (f.confidence * 100).round, f.type, target)
-        f.evidence.each { |e| @io.puts "        - #{e}" }
-        @io.puts "        fix: #{f.suggested_fix}"
+      def render_clean
+        @io.puts @a.paint("  ✓ no findings — schema is lean", :green, :bold)
+      end
+
+      def header
+        @io.puts
+        @io.puts "  #{@a.paint("schema_reaper", :bold)}  " \
+                 "#{@a.paint("#{@findings.size} finding#{"s" unless @findings.size == 1}", :bold)}  " \
+                 "#{@a.paint("~#{Bytes.human(total_reclaimable)} reclaimable", :dim)}"
+        @io.puts
+      end
+
+      def grouped
+        @findings
+          .sort_by { |f| [-f.confidence, SEV_ORDER.fetch(f.severity, 9)] }
+          .group_by(&:table)
+      end
+
+      def render_table(table, group)
+        @io.puts "  #{@a.paint(table, :bold, :magenta)}"
+        group.each { |f| render_finding(f) }
+        @io.puts
+      end
+
+      def render_finding(finding)
+        @io.puts finding_head(finding)
+        @io.puts "           #{@a.paint(evidence_line(finding), :dim)}"
+        fix = "→ #{finding.suggested_fix}"
+        @io.puts "           #{@a.paint(fix, :green)}"
+      end
+
+      def finding_head(finding)
+        pct = (finding.confidence * 100).round
+        bar = @a.confidence_bar(finding.confidence, finding.severity)
+        sev = @a.severity(finding.severity, format("%-6s", finding.severity))
+        label = finding.target_label
+        type_text = label ? format("%-19s", finding.type) : finding.type.to_s
+
+        head = format("    %s %3d%%  %s  %s", bar, pct, sev, @a.paint(type_text, :bold))
+        head << "  #{label}" if label
+        head << rjust_bytes(finding)
+        head
       end
 
-      def sorted
-        @findings.sort_by { |f| [-f.confidence, SEV_ORDER.fetch(f.severity, 9)] }
+      def rjust_bytes(finding)
+        return "" unless finding.reclaimable_bytes.positive?
+
+        human = Bytes.human(finding.reclaimable_bytes)
+        "  #{@a.paint(human, :dim)}"
+      end
+
+      def evidence_line(finding)
+        finding.evidence.join(" · ")
+      end
+
+      def footer
+        by_sev = @findings.group_by(&:severity)
+        tally = SEV_ORDER.keys.filter_map do |sev|
+          n = by_sev[sev]&.size
+          @a.severity(sev, "#{sev} #{n}") if n
+        end.join("   ")
+
+        by_type = @findings.group_by(&:type).transform_values(&:size)
+                           .sort_by { |_t, n| -n }
+                           .map { |t, n| "#{t} #{n}" }.join(" · ")
+
+        @io.puts "  #{tally}"
+        @io.puts "  #{@a.paint(by_type, :dim)}"
       end
 
       def total_reclaimable

data/lib/schema_reaper/reporters/trend.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative "bytes"
+require_relative "console"
+
+module SchemaReaper
+  module Reporters
+    # Formats History#trend into a readable progress block instead of a raw
+    # hash dump.
+    class Trend
+      def initialize(data, io: $stdout, color: nil)
+        @d = data
+        @c = Console.new(out: io, color: color)
+      end
+
+      def render
+        snaps = @d[:snapshots].to_i
+        @c.title("trend", "#{snaps} snapshot#{"s" unless snaps == 1}")
+
+        if snaps.zero?
+          @c.info("no snapshots yet — run `schema_reaper trend` to record the first.")
+          return
+        end
+        if snaps == 1
+          @c.info("first snapshot recorded. Run this again later to see the delta.")
+          dates
+          return
+        end
+
+        counts
+        bytes
+        @c.blank
+        @c.list("new since last run:", @d[:newly_introduced].to_a, colour: :yellow)
+        @c.list("resolved since last run:", @d[:resolved_since_prev].to_a, colour: :green)
+        @c.blank
+        dates
+      end
+
+      private
+
+      def counts
+        total = signed(@d[:count_change_total])
+        last = signed(@d[:count_change_last])
+        @c.row("findings", @d.fetch(:latest_count, "—"),
+               "#{total} since first run · #{last} since last")
+      end
+
+      def bytes
+        delta = @d[:bytes_change_total].to_i
+        sign = delta.positive? ? "+" : "-"
+        @c.row("reclaimable", Bytes.human(@d.fetch(:latest_bytes, 0)),
+               "#{sign}#{Bytes.human(delta.abs)} since first run")
+      end
+
+      def dates
+        @c.row("first snapshot", short(@d[:first_at]))
+        @c.row("latest", short(@d[:last_at]))
+      end
+
+      def signed(number)
+        n = number.to_i
+        n.positive? ? "+#{n}" : n.to_s
+      end
+
+      def short(iso)
+        iso.to_s.split("T").first
+      end
+    end
+  end
+end

data/lib/schema_reaper/runner.rb

@@ -37,9 +37,11 @@ module SchemaReaper
     def warn_missing_query_history(db)
       return if db.query_history?
 
-      warn "schema_reaper: skipping unused_index -- only #{db.index_scan_total} index scan(s) " \
-           "recorded across #{db.index_count} index(es). Scan a database that has served " \
-           "production traffic, or check whether statistics were recently reset."
+      Reporters::Console.new.notice(
+        "unused_index skipped — only #{db.index_scan_total} scan(s) across " \
+        "#{db.index_count} indexes, so there is no query history to judge by. " \
+        "Run against a database that has served production traffic."
+      )
     end
 
     def dedupe(findings)

data/lib/schema_reaper/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SchemaReaper
-  VERSION = "1.0.8"
+  VERSION = "1.0.9"
 end

data/lib/schema_reaper.rb

@@ -18,7 +18,10 @@ require_relative "schema_reaper/analyzers/missing_fk_index"
 require_relative "schema_reaper/analyzers/always_null_column"
 require_relative "schema_reaper/analyzers/single_value_column"
 require_relative "schema_reaper/reporters/bytes"
+require_relative "schema_reaper/reporters/ansi"
+require_relative "schema_reaper/reporters/console"
 require_relative "schema_reaper/reporters/table"
+require_relative "schema_reaper/reporters/trend"
 require_relative "schema_reaper/reporters/json"
 require_relative "schema_reaper/reporters/markdown"
 require_relative "schema_reaper/reporters/sarif"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: schema_reaper
 version: !ruby/object:Gem::Version
-  version: 1.0.8
+  version: 1.0.9
 platform: ruby
 authors:
 - aksshatt
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2026-09-04 00:00:00.000000000 Z
+date: 2026-09-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: prism
@@ -103,6 +103,7 @@ files:
 - LICENSE.txt
 - PRO.md
 - README.md
+- RELEASE_CHECKLIST.md
 - Rakefile
 - exe/schema_reaper
 - lib/schema_reaper.rb
@@ -118,17 +119,21 @@ files:
 - lib/schema_reaper/baseline.rb
 - lib/schema_reaper/cli.rb
 - lib/schema_reaper/config.rb
+- lib/schema_reaper/database_url.rb
 - lib/schema_reaper/finding.rb
 - lib/schema_reaper/gem_awareness.rb
 - lib/schema_reaper/history.rb
 - lib/schema_reaper/introspect/postgres.rb
 - lib/schema_reaper/migration_generator.rb
 - lib/schema_reaper/railtie.rb
+- lib/schema_reaper/reporters/ansi.rb
 - lib/schema_reaper/reporters/bytes.rb
+- lib/schema_reaper/reporters/console.rb
 - lib/schema_reaper/reporters/json.rb
 - lib/schema_reaper/reporters/markdown.rb
 - lib/schema_reaper/reporters/sarif.rb
 - lib/schema_reaper/reporters/table.rb
+- lib/schema_reaper/reporters/trend.rb
 - lib/schema_reaper/runner.rb
 - lib/schema_reaper/runtime.rb
 - lib/schema_reaper/schema.rb