bulletin-rb 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8e9c2c120bd6a1529e539a910573d3d6c900263cfba6d18f5670d2e6daecaeb4
+  data.tar.gz: cf7559388fe0d95ec84fb8b9544f616a045fde3183f4026bc9828d1309926d44
+SHA512:
+  metadata.gz: 33537b40f838bb67a319ada12e36ade3f41945602f12ae687e191e831d28ece51fad749723295b68ad40e2621b8863cf649fa939330c6c5e3574d7367e75df4d
+  data.tar.gz: 6bb1f8ff05ad42bf356dd629fff857a73f41f526fa980bb5cdc66f3b07a8ac09c45fc55da0dcf934e7edf3aa1c58897b2b0bf0fab104c03bbfa5c4baa605eff9

data/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project are documented here. 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).
+
+## [Unreleased]
+
+### Added
+- Extracted Bulletin into its own repository as a standalone, installable gem,
+  published as `bulletin-rb` (the namespace stays `Bulletin`; a `lib/bulletin-rb.rb`
+  shim preserves `require "bulletin"`).
+- Dev/test harness: `test/dummy` Rails app, Minitest suite (fingerprint,
+  warning extraction, ActiveRecord store, engine mount), and CI.
+
+## [0.1.0]
+
+### Added
+- Initial MVP: Rack middleware inserted inside `Bullet::Rack` that reads
+  Bullet's per-request notifications and persists them as fingerprinted issues.
+- ActiveRecord store with per-issue occurrence cap, regression reopen, and
+  retention pruning.
+- Mountable engine with an issues triage UI and an install generator.

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2026 Charles Harris
+
+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,64 @@
+# Bulletin
+
+A mountable Rails engine that gives [Bullet](https://github.com/flyerhzm/bullet) a memory.
+
+Bullet is a great *sensor* — it detects N+1 queries, unused eager loading, and
+missing counter caches on every request — but it has no *memory*: each warning
+flashes in the footer/log and is gone. Bulletin reads Bullet's per-request
+findings, fingerprints them into durable **issues** (Sentry-style), and exposes
+a mounted UI for triage (Flipper UI / PgHero in spirit).
+
+```
+Bullet (sensor)  →  Bulletin (memory)  →  mounted UI (attention)
+```
+
+## Install
+
+```ruby
+# Gemfile (typically the :development group, alongside bullet)
+gem "bulletin-rb"   # the Ruby namespace is still `Bulletin`
+```
+
+```bash
+bundle install
+bin/rails generate bulletin:install   # writes config/initializers/bulletin.rb
+bin/rails db:migrate                   # creates bulletin_issues / bulletin_occurrences
+```
+
+```ruby
+# config/routes.rb
+mount Bulletin::Engine => "/bulletin"
+```
+
+Visit `/bulletin`.
+
+## How it works
+
+- A Rack middleware is inserted **inside** `Bullet::Rack`. On the response
+  unwind it reads Bullet's already-deduped `notification_collector.collection`
+  (before Bullet clears it), attaches request context from the Rack env, and
+  hands a JSON-safe payload to the store.
+- Warnings are **fingerprinted** by `kind + model + association(s) +
+  controller#action` — deliberately *not* file:line, so refactors don't spawn
+  duplicate issues. The precise call stack is kept per occurrence instead.
+- Each issue carries Bullet's own **suggested fix**. Occurrences are capped per
+  issue; a resolved issue that recurs is automatically **reopened**.
+
+## Configuration
+
+See `config/initializers/bulletin.rb`. Key knobs:
+
+| Option | Default | Notes |
+| --- | --- | --- |
+| `store` | `:active_record` | `:null` disables; `:redis`/`:hybrid` planned |
+| `write_strategy` | `:active_job` | `:inline` for zero-setup local dev |
+| `occurrence_cap` | `50` | rows kept per issue |
+| `retention` | `7.days` | `PruneJob` ages out older issues |
+| `enabled` | follows `Bullet.enable?` | dev/staging only by default |
+| `authenticate_with` | dev-only | `->(request) { ... }` like Sidekiq::Web |
+
+## Status
+
+MVP. The store is abstracted behind a single `Bulletin::Store` boundary so a
+Redis hot-path + hybrid drain (and a live occurrence view) can land later
+without touching the middleware or UI.

data/app/controllers/bulletin/application_controller.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Bulletin
+  class ApplicationController < ActionController::Base
+    protect_from_forgery with: :exception
+    layout "bulletin/application"
+
+    before_action :authenticate_bulletin!
+
+    private
+
+    # Mirrors the Sidekiq::Web / Flipper pattern: delegate auth to the host via
+    # a configurable callable, and fail closed outside development by default.
+    def authenticate_bulletin!
+      auth = Bulletin.config.authenticate_with
+
+      if auth
+        head :forbidden unless auth.call(request)
+      elsif !Rails.env.development?
+        head :forbidden
+      end
+    end
+  end
+end

data/app/controllers/bulletin/issues_controller.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Bulletin
+  class IssuesController < ApplicationController
+    before_action :set_issue, only: %i[show resolve mute reopen]
+
+    def index
+      @issues = Issue.recent
+      @issues = @issues.where(kind: params[:kind]) if params[:kind].present?
+      @issues = @issues.where(status: params[:status]) if params[:status].present?
+      @kinds  = Issue.distinct.pluck(:kind).compact.sort
+    end
+
+    def show
+      @occurrences = @issue.occurrences.order(created_at: :desc).limit(Bulletin.config.occurrence_cap)
+    end
+
+    def resolve
+      @issue.resolve!
+      redirect_back fallback_location: issues_path, notice: "Issue resolved."
+    end
+
+    def mute
+      @issue.mute!
+      redirect_back fallback_location: issues_path, notice: "Issue muted."
+    end
+
+    def reopen
+      @issue.reopen!
+      redirect_back fallback_location: issues_path, notice: "Issue reopened."
+    end
+
+    private
+
+    def set_issue
+      @issue = Issue.find(params[:id])
+    end
+  end
+end

data/app/jobs/bulletin/prune_job.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Bulletin
+  # Enqueue periodically (e.g. from cron / a recurring job) to age out issues
+  # past the configured retention window.
+  class PruneJob < ::ActiveJob::Base
+    queue_as { Bulletin.config.job_queue }
+
+    def perform
+      Bulletin.store.prune!
+    end
+  end
+end

data/app/jobs/bulletin/record_job.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Bulletin
+  # Drains a request's normalized warning payload into the store off the request
+  # path. Self-contained (inherits ActiveJob::Base, not the host's ApplicationJob)
+  # so the engine works regardless of the host's job setup.
+  class RecordJob < ::ActiveJob::Base
+    queue_as { Bulletin.config.job_queue }
+
+    def perform(payload)
+      Bulletin.store.record(payload)
+    end
+  end
+end

data/app/models/bulletin/application_record.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Bulletin
+  class ApplicationRecord < ::ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/models/bulletin/issue.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Bulletin
+  # One row per fingerprint — the triage unit. Holds Bullet's own fix advice
+  # plus aggregate stats, so the list view is a single cheap query.
+  class Issue < ApplicationRecord
+    self.table_name = "bulletin_issues"
+
+    has_many :occurrences,
+             class_name: "Bulletin::Occurrence",
+             foreign_key: :bulletin_issue_id,
+             inverse_of: :issue,
+             dependent: :delete_all
+
+    enum :status, { active: 0, resolved: 1, muted: 2 }
+
+    serialize :associations, coder: JSON, type: Array
+
+    validates :fingerprint, presence: true, uniqueness: true
+
+    scope :recent, -> { order(last_seen_at: :desc) }
+
+    def association_label
+      Array(associations).join(", ")
+    end
+
+    def label
+      [base_class, association_label].reject(&:blank?).join(" → ")
+    end
+
+    def endpoint
+      [controller, action].compact.join("#")
+    end
+
+    def resolve!
+      update!(status: :resolved, resolved_at: Time.now)
+    end
+
+    def reopen!
+      update!(status: :active, resolved_at: nil)
+    end
+
+    def mute!(until_time = nil)
+      update!(status: :muted, muted_until: until_time)
+    end
+  end
+end

data/app/models/bulletin/occurrence.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Bulletin
+  # A single recorded instance of an issue — the evidence (where/when/stack).
+  # Capped per issue by Store::ActiveRecord so a hammered endpoint can't flood
+  # the table.
+  class Occurrence < ApplicationRecord
+    self.table_name = "bulletin_occurrences"
+
+    belongs_to :issue,
+               class_name: "Bulletin::Issue",
+               foreign_key: :bulletin_issue_id,
+               inverse_of: :occurrences
+
+    serialize :backtrace, coder: JSON, type: Array
+
+    def endpoint
+      [controller, action].compact.join("#")
+    end
+  end
+end

data/app/views/bulletin/issues/index.html.erb

@@ -0,0 +1,39 @@
+<%= form_with url: issues_path, method: :get, class: "filters" do %>
+  <%= select_tag :kind,
+        options_for_select([["All kinds", ""]] + @kinds.map { |k| [k.humanize, k] }, params[:kind]) %>
+  <%= select_tag :status,
+        options_for_select([["All statuses", ""], %w[Active active], %w[Resolved resolved], %w[Muted muted]], params[:status]) %>
+  <button type="submit">Filter</button>
+  <% if params[:kind].present? || params[:status].present? %>
+    <%= link_to "Clear", issues_path %>
+  <% end %>
+<% end %>
+
+<% if @issues.any? %>
+  <table>
+    <thead>
+      <tr>
+        <th>Kind</th>
+        <th>Issue</th>
+        <th>Endpoint</th>
+        <th>Count</th>
+        <th>Last seen</th>
+        <th>Status</th>
+      </tr>
+    </thead>
+    <tbody>
+      <% @issues.each do |issue| %>
+        <tr>
+          <td><span class="badge <%= issue.kind %>"><%= issue.kind.humanize %></span></td>
+          <td><%= link_to issue.label.presence || "(unknown)", issue_path(issue) %></td>
+          <td><code><%= issue.endpoint %></code></td>
+          <td><%= issue.occurrence_count %></td>
+          <td class="muted"><%= issue.last_seen_at&.strftime("%b %-d, %H:%M") %></td>
+          <td><span class="status <%= issue.status %>"><%= issue.status %></span></td>
+        </tr>
+      <% end %>
+    </tbody>
+  </table>
+<% else %>
+  <div class="empty">No warnings recorded yet. Exercise the app and they'll show up here.</div>
+<% end %>

data/app/views/bulletin/issues/show.html.erb

@@ -0,0 +1,61 @@
+<p><%= link_to "← All issues", issues_path %></p>
+
+<div class="summary">
+  <div style="display:flex; justify-content:space-between; align-items:flex-start; gap:16px;">
+    <div>
+      <span class="badge <%= @issue.kind %>"><%= @issue.kind.humanize %></span>
+      <h2 style="margin:8px 0;"><%= @issue.label %></h2>
+    </div>
+    <div class="actions">
+      <% if @issue.active? %>
+        <%= button_to "Resolve", resolve_issue_path(@issue), method: :patch %>
+        <%= button_to "Mute", mute_issue_path(@issue), method: :patch %>
+      <% else %>
+        <%= button_to "Reopen", reopen_issue_path(@issue), method: :patch %>
+      <% end %>
+    </div>
+  </div>
+
+  <dl>
+    <dt>Status</dt><dd><span class="status <%= @issue.status %>"><%= @issue.status %></span></dd>
+    <dt>Endpoint</dt><dd><code><%= @issue.endpoint %></code></dd>
+    <dt>Occurrences</dt><dd><%= @issue.occurrence_count %></dd>
+    <dt>First seen</dt><dd><%= @issue.first_seen_at&.strftime("%b %-d, %Y %H:%M") %></dd>
+    <dt>Last seen</dt><dd><%= @issue.last_seen_at&.strftime("%b %-d, %Y %H:%M") %></dd>
+  </dl>
+
+  <% if @issue.advice.present? %>
+    <h3>Suggested fix</h3>
+    <pre><%= @issue.advice %></pre>
+  <% end %>
+</div>
+
+<h3>Recent occurrences <span class="muted">(<%= @occurrences.size %>)</span></h3>
+<% if @occurrences.any? %>
+  <table>
+    <thead>
+      <tr><th>When</th><th>Endpoint</th><th>Path</th><th>Stack</th></tr>
+    </thead>
+    <tbody>
+      <% @occurrences.each do |occ| %>
+        <tr>
+          <td class="muted"><%= occ.created_at&.strftime("%b %-d, %H:%M:%S") %></td>
+          <td><code><%= occ.endpoint %></code></td>
+          <td class="muted"><%= occ.path %></td>
+          <td>
+            <% if occ.backtrace.present? %>
+              <details>
+                <summary class="muted">stack (<%= occ.backtrace.size %>)</summary>
+                <pre><%= occ.backtrace.join("\n") %></pre>
+              </details>
+            <% else %>
+              <span class="muted">—</span>
+            <% end %>
+          </td>
+        </tr>
+      <% end %>
+    </tbody>
+  </table>
+<% else %>
+  <div class="empty">No occurrences retained.</div>
+<% end %>

data/app/views/layouts/bulletin/application.html.erb

@@ -0,0 +1,57 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Bulletin</title>
+    <meta name="viewport" content="width=device-width,initial-scale=1">
+    <%= csrf_meta_tags %>
+    <style>
+      :root { --fg:#1f2933; --muted:#6b7280; --line:#e5e7eb; --bg:#f9fafb;
+              --red:#9b1c1c; --redbg:#fdf2f2; --green:#0f766e; --amber:#92400e; }
+      * { box-sizing: border-box; }
+      body { margin:0; font:14px/1.5 -apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;
+             color:var(--fg); background:var(--bg); }
+      header { background:#fff; border-bottom:1px solid var(--line); padding:14px 24px; }
+      header h1 { margin:0; font-size:18px; }
+      header h1 a { color:var(--fg); text-decoration:none; }
+      header .tag { color:var(--muted); font-weight:400; font-size:13px; }
+      main { max-width:1100px; margin:0 auto; padding:24px; }
+      .flash { background:#ecfdf5; color:var(--green); border:1px solid #a7f3d0;
+               padding:8px 12px; border-radius:6px; margin-bottom:16px; }
+      table { width:100%; border-collapse:collapse; background:#fff;
+              border:1px solid var(--line); border-radius:8px; overflow:hidden; }
+      th, td { text-align:left; padding:10px 12px; border-bottom:1px solid var(--line); vertical-align:top; }
+      th { background:#fafafa; font-size:12px; text-transform:uppercase; letter-spacing:.03em; color:var(--muted); }
+      tr:last-child td { border-bottom:none; }
+      a { color:#2563eb; text-decoration:none; }
+      a:hover { text-decoration:underline; }
+      code, pre { font-family:ui-monospace,SFMono-Regular,Menlo,monospace; font-size:12px; }
+      pre { background:#0f172a; color:#e2e8f0; padding:12px; border-radius:6px; overflow:auto; }
+      .badge { display:inline-block; padding:1px 8px; border-radius:999px; font-size:12px; font-weight:600; }
+      .badge.n_plus_one_query { background:var(--redbg); color:var(--red); }
+      .badge.unused_eager_loading { background:#fffbeb; color:var(--amber); }
+      .badge.counter_cache { background:#eff6ff; color:#1d4ed8; }
+      .status.active { color:var(--red); font-weight:600; }
+      .status.resolved { color:var(--green); }
+      .status.muted { color:var(--muted); }
+      .muted { color:var(--muted); }
+      .filters { margin-bottom:16px; display:flex; gap:8px; align-items:center; }
+      .filters select, .filters button { padding:6px 8px; border:1px solid var(--line); border-radius:6px; background:#fff; }
+      .actions form { display:inline; }
+      .actions button { padding:4px 10px; border:1px solid var(--line); border-radius:6px;
+                        background:#fff; cursor:pointer; font-size:13px; }
+      .summary { background:#fff; border:1px solid var(--line); border-radius:8px; padding:16px; margin-bottom:20px; }
+      .summary dl { display:grid; grid-template-columns:140px 1fr; gap:6px 16px; margin:0; }
+      .summary dt { color:var(--muted); }
+      .empty { color:var(--muted); padding:40px; text-align:center; }
+    </style>
+  </head>
+  <body>
+    <header>
+      <h1><%= link_to "Bulletin", root_path %> <span class="tag">— a memory for Bullet</span></h1>
+    </header>
+    <main>
+      <% if notice %><div class="flash"><%= notice %></div><% end %>
+      <%= yield %>
+    </main>
+  </body>
+</html>

data/config/routes.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+Bulletin::Engine.routes.draw do
+  resources :issues, only: %i[index show] do
+    member do
+      patch :resolve
+      patch :mute
+      patch :reopen
+    end
+  end
+
+  root to: "issues#index"
+end

data/db/migrate/20260527000001_create_bulletin_tables.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+class CreateBulletinTables < ActiveRecord::Migration[7.1]
+  def change
+    create_table :bulletin_issues do |t|
+      t.string   :fingerprint, null: false
+      t.string   :kind
+      t.string   :base_class
+      t.text     :associations
+      t.string   :controller
+      t.string   :action
+      t.text     :advice
+      t.integer  :status, null: false, default: 0
+      t.datetime :resolved_at
+      t.datetime :muted_until
+      t.integer  :occurrence_count, null: false, default: 0
+      t.datetime :first_seen_at
+      t.datetime :last_seen_at
+      t.timestamps
+    end
+    add_index :bulletin_issues, :fingerprint, unique: true
+    add_index :bulletin_issues, :last_seen_at
+    add_index :bulletin_issues, :status
+
+    create_table :bulletin_occurrences do |t|
+      t.references :bulletin_issue, null: false, foreign_key: true, index: false
+      t.string   :controller
+      t.string   :action
+      t.string   :path
+      t.string   :request_id
+      t.text     :backtrace
+      t.datetime :created_at, null: false
+    end
+    add_index :bulletin_occurrences, %i[bulletin_issue_id created_at]
+  end
+end

data/lib/bulletin/configuration.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Bulletin
+  # Host-facing configuration. Sensible dev-first defaults; the seams that
+  # matter for a future production story (store backend, write strategy) are
+  # decoupled so they can evolve independently.
+  class Configuration
+    attr_accessor :write_strategy, :job_queue, :occurrence_cap, :authenticate_with
+    attr_reader :store, :retention
+
+    def initialize
+      @store            = :active_record # :active_record | :null  (seam for :redis/:hybrid)
+      @write_strategy   = :active_job    # :active_job | :inline
+      @job_queue        = :bulletin
+      @retention        = 7 * 24 * 60 * 60 # seconds; coerced from Durations too
+      @occurrence_cap   = 50               # max occurrence rows kept per issue
+      @enabled          = nil              # nil => follow Bullet.enable?
+      @authenticate_with = nil             # ->(request) { ... } ; nil => dev-only access
+    end
+
+    def store=(name)
+      @store = name.to_sym
+      Bulletin.reset_store!
+      @store
+    end
+
+    def retention=(value)
+      # Accept ActiveSupport::Duration (7.days) or a raw seconds Numeric.
+      @retention = value.respond_to?(:to_i) ? value.to_i : value
+    end
+
+    def retention_cutoff
+      Time.now - retention
+    end
+
+    # Whether Bulletin should record at all. Defaults to Bullet's own switch so
+    # it inherits Bullet's dev/staging-only posture unless explicitly overridden.
+    def enabled?
+      return defined?(Bullet) && Bullet.enable? if @enabled.nil?
+
+      @enabled.respond_to?(:call) ? !!@enabled.call : !!@enabled
+    end
+
+    def enabled=(value)
+      @enabled = value
+    end
+  end
+end

data/lib/bulletin/engine.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "rails/engine"
+
+module Bulletin
+  class Engine < ::Rails::Engine
+    isolate_namespace Bulletin
+
+    # Run after Bullet has inserted its own middleware so Bullet::Rack exists in
+    # the stack; insert_after places us inside it. If Bullet isn't loaded (e.g.
+    # production, where it's typically a dev-only dependency), we no-op.
+    initializer "bulletin.middleware", after: "bullet.add_middleware" do |app|
+      app.middleware.insert_after Bullet::Rack, Bulletin::Middleware if defined?(Bullet::Rack)
+    end
+
+    # Let the host pick up the engine's migrations with a plain `rails db:migrate`,
+    # without copying them. (A consumer can still run the install generator.)
+    initializer "bulletin.migrations" do |app|
+      next if app.root.to_s == root.to_s
+
+      config.paths["db/migrate"].expanded.each do |expanded_path|
+        app.config.paths["db/migrate"] << expanded_path
+        ::ActiveRecord::Migrator.migrations_paths << expanded_path if defined?(::ActiveRecord::Migrator)
+      end
+    end
+  end
+end

data/lib/bulletin/fingerprint.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Bulletin
+  # The identity of an "issue". Deliberately built from stable facts only:
+  # the kind of problem, the model, the association(s), and the
+  # controller#action that triggered it. File/line is intentionally excluded
+  # so a refactor doesn't spawn duplicate issues — that detail lives on each
+  # occurrence instead.
+  module Fingerprint
+    module_function
+
+    def for(kind:, base_class:, associations:, controller:, action:)
+      raw = [
+        kind,
+        base_class,
+        Array(associations).map(&:to_s).sort.join(","),
+        controller,
+        action
+      ].map(&:to_s).join("|")
+
+      Digest::SHA256.hexdigest(raw)
+    end
+  end
+end

data/lib/bulletin/middleware.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Bulletin
+  # Inserted *after* Bullet::Rack (i.e. inside it), so on the response unwind we
+  # run before Bullet's own `ensure` nulls the thread-local collector. We read
+  # the already-deduped notifications, attach request context from the env
+  # (Bullet never populates notification.path), and hand a JSON-safe payload to
+  # the store. Persistence failures are swallowed — Bulletin must never break a
+  # host request.
+  class Middleware
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      status, headers, body = @app.call(env)
+
+      begin
+        persist(env) if recordable?
+      rescue StandardError => e
+        Bulletin.logger&.error("[Bulletin] failed to record warnings: #{e.class}: #{e.message}")
+      end
+
+      [status, headers, body]
+    end
+
+    private
+
+    def recordable?
+      Bulletin.config.enabled? &&
+        defined?(Bullet) && Bullet.enable? && Bullet.start?
+    end
+
+    def persist(env)
+      # Force unused-eager-loading detection to finalize; it isn't added to the
+      # collection until notification? runs (Bullet does this just after us, but
+      # we'd miss it otherwise). Re-running is harmless — the collector is a Set.
+      Bullet.notification?
+
+      collector = Bullet.notification_collector
+      collection = collector && collector.collection
+      return if collection.nil? || collection.empty?
+
+      warnings = collection.map { |notification| Bulletin::Warning.from(notification) }
+      Bulletin.dispatch(request_context(env).merge("warnings" => warnings))
+    end
+
+    def request_context(env)
+      params = env["action_dispatch.request.path_parameters"] || {}
+      {
+        "controller" => params[:controller],
+        "action"     => params[:action],
+        "path"       => env["PATH_INFO"],
+        "request_id" => env["action_dispatch.request_id"]
+      }
+    end
+  end
+end

data/lib/bulletin/store/active_record.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Bulletin
+  module Store
+    # Durable backend: one issue row per fingerprint, with a capped ring of
+    # occurrence rows as evidence. Aggregate stats (count, first/last seen)
+    # live on the issue so the list view never has to scan occurrences.
+    class ActiveRecord < Base
+      def record(payload)
+        warnings = Array(payload["warnings"])
+        return if warnings.empty?
+
+        warnings.each { |warning| record_one(warning, payload) }
+      end
+
+      def prune!
+        Bulletin::Issue.where(arel_last_seen.lt(Bulletin.config.retention_cutoff)).find_each(&:destroy)
+      end
+
+      private
+
+      def arel_last_seen
+        Bulletin::Issue.arel_table[:last_seen_at]
+      end
+
+      def record_one(warning, context)
+        fingerprint = Bulletin::Fingerprint.for(
+          kind: warning["kind"],
+          base_class: warning["base_class"],
+          associations: warning["associations"],
+          controller: context["controller"],
+          action: context["action"]
+        )
+        issue = upsert_issue(fingerprint, warning, context)
+        append_occurrence(issue, warning, context)
+      end
+
+      def upsert_issue(fingerprint, warning, context)
+        now   = Time.now
+        issue = Bulletin::Issue.find_or_initialize_by(fingerprint: fingerprint)
+
+        issue.kind         ||= warning["kind"]
+        issue.base_class   ||= warning["base_class"]
+        issue.controller   ||= context["controller"]
+        issue.action       ||= context["action"]
+        issue.associations   = warning["associations"] if issue.associations.blank?
+        issue.advice         = warning["advice"]
+        issue.first_seen_at ||= now
+        issue.last_seen_at   = now
+        issue.occurrence_count = issue.occurrence_count.to_i + 1
+
+        # Regression detection: a resolved issue that recurs is reopened.
+        if issue.persisted? && issue.resolved?
+          issue.status      = :active
+          issue.resolved_at = nil
+        end
+
+        issue.save!
+        issue
+      rescue ::ActiveRecord::RecordNotUnique
+        retry # another worker created the issue first; reload and bump it
+      end
+
+      def append_occurrence(issue, warning, context)
+        issue.occurrences.create!(
+          controller: context["controller"],
+          action:     context["action"],
+          path:       context["path"],
+          request_id: context["request_id"],
+          backtrace:  warning["backtrace"]
+        )
+        enforce_cap(issue)
+      end
+
+      def enforce_cap(issue)
+        cap = Bulletin.config.occurrence_cap
+        return unless cap.to_i.positive?
+
+        excess_ids = issue.occurrences.order(created_at: :desc).offset(cap).pluck(:id)
+        Bulletin::Occurrence.where(id: excess_ids).delete_all if excess_ids.any?
+      end
+    end
+  end
+end

data/lib/bulletin/store/base.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Bulletin
+  module Store
+    # Interface contract for persistence backends.
+    class Base
+      # payload is a JSON-safe Hash:
+      #   { "controller" =>, "action" =>, "path" =>, "request_id" =>,
+      #     "warnings" => [ { "kind", "base_class", "associations", "advice", "backtrace" }, ... ] }
+      def record(_payload)
+        raise NotImplementedError, "#{self.class} must implement #record"
+      end
+
+      # Remove issues/occurrences older than the configured retention window.
+      def prune!
+        raise NotImplementedError, "#{self.class} must implement #prune!"
+      end
+    end
+  end
+end

data/lib/bulletin/store/null.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Bulletin
+  module Store
+    # No-op backend. Useful in tests and as a kill switch.
+    class Null < Base
+      def record(_payload); end
+
+      def prune!; end
+    end
+  end
+end

data/lib/bulletin/store.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Bulletin
+  # The single write boundary. Every backend (today: ActiveRecord/Null; later:
+  # Redis/hybrid) implements the same interface, so the middleware, jobs, and
+  # UI never need to know how warnings are stored.
+  module Store
+    BACKENDS = {
+      active_record: "Bulletin::Store::ActiveRecord",
+      null: "Bulletin::Store::Null"
+    }.freeze
+
+    module_function
+
+    def build(name)
+      class_name = BACKENDS.fetch(name.to_sym) do
+        raise ArgumentError, "Unknown Bulletin store: #{name.inspect} (expected one of #{BACKENDS.keys})"
+      end
+      Object.const_get(class_name).new
+    end
+  end
+end

data/lib/bulletin/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Bulletin
+  VERSION = "0.1.0"
+end

data/lib/bulletin/warning.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Bulletin
+  # Converts a Bullet notification object into a plain, JSON-safe Hash that can
+  # survive serialization across an ActiveJob boundary (the thread-local
+  # collector is gone by the time a job runs, so we extract eagerly).
+  #
+  # Notes from Bullet 8.x internals:
+  #   - `notification.path` is always nil (detectors never pass it), so request
+  #     context comes from the Rack env instead, not from here.
+  #   - `title`/`body` are public and together form Bullet's own fix advice.
+  #   - the call stack lives in @callers (N+1 and unused-eager-loading only;
+  #     counter-cache notifications have none) and is reachable only via an
+  #     ivar because the subclasses mark `call_stack_messages` protected.
+  module Warning
+    module_function
+
+    def from(notification)
+      {
+        "kind"         => kind_for(notification),
+        "base_class"   => notification.base_class.to_s,
+        "associations" => Array(notification.associations).map(&:to_s),
+        "advice"       => advice_for(notification),
+        "backtrace"    => backtrace_for(notification)
+      }
+    end
+
+    def kind_for(notification)
+      # Bullet::Notification::NPlusOneQuery => "n_plus_one_query"
+      ActiveSupport::Inflector.underscore(notification.class.name.split("::").last)
+    end
+
+    def advice_for(notification)
+      [safe(notification, :title), safe(notification, :body)].compact.join("\n").strip
+    end
+
+    def backtrace_for(notification)
+      Array(notification.instance_variable_get(:@callers)).map(&:to_s)
+    end
+
+    def safe(notification, method)
+      notification.public_send(method)
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/bulletin-rb.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# The gem is published as "bulletin-rb", so Bundler's auto-require looks for
+# "bulletin-rb". The real entrypoint is "bulletin" (namespace `Bulletin`); this
+# shim bridges the two so `gem "bulletin-rb"` works with no `require:` option.
+require "bulletin"

data/lib/bulletin.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "bulletin/version"
+require "bulletin/configuration"
+require "bulletin/fingerprint"
+require "bulletin/warning"
+require "bulletin/store"
+require "bulletin/store/base"
+require "bulletin/store/null"
+require "bulletin/store/active_record"
+require "bulletin/middleware"
+require "bulletin/engine" if defined?(::Rails::Engine)
+
+# Bulletin gives Bullet a memory. Bullet detects N+1 / unused-eager-loading /
+# counter-cache problems per request but forgets them immediately; Bulletin
+# reads Bullet's per-request findings, fingerprints them into durable "issues"
+# (Sentry-style), and exposes a mountable UI for triage.
+module Bulletin
+  class << self
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure
+      yield config
+    end
+
+    # The active persistence backend (memoized). Reset when the store changes.
+    def store
+      @store ||= Store.build(config.store)
+    end
+
+    def reset_store!
+      @store = nil
+    end
+
+    # Routes a normalized payload to the store, inline or via ActiveJob,
+    # depending on the configured write strategy.
+    def dispatch(payload)
+      case config.write_strategy
+      when :active_job
+        RecordJob.perform_later(payload)
+      else # :inline
+        store.record(payload)
+      end
+    end
+
+    def logger
+      return Rails.logger if defined?(Rails) && Rails.respond_to?(:logger)
+
+      nil
+    end
+  end
+end

data/lib/generators/bulletin/install_generator.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module Bulletin
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates a Bulletin initializer in the host application."
+
+      def copy_initializer
+        template "bulletin.rb", "config/initializers/bulletin.rb"
+      end
+
+      def show_post_install
+        say ""
+        say "Bulletin installed.", :green
+        say "  1. Run `bin/rails db:migrate` to create its tables."
+        say "  2. Mount it in config/routes.rb:  mount Bulletin::Engine => \"/bulletin\""
+      end
+    end
+  end
+end

data/lib/generators/bulletin/templates/bulletin.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+Bulletin.configure do |config|
+  # Persistence backend. :active_record is the only durable backend today;
+  # :null disables recording. (:redis / :hybrid are planned.)
+  # config.store = :active_record
+
+  # How warnings are written. :active_job keeps recording off the request path
+  # (recommended); :inline writes synchronously (handy in development with no
+  # worker running).
+  # config.write_strategy = :active_job
+
+  # ActiveJob queue used when write_strategy is :active_job.
+  # config.job_queue = :bulletin
+
+  # Max occurrence rows kept per issue (older ones are pruned).
+  # config.occurrence_cap = 50
+
+  # How long issues are retained; PruneJob deletes anything older.
+  # config.retention = 7.days
+
+  # Whether to record. Defaults to Bullet.enable? (dev/staging only).
+  # config.enabled = Rails.env.local?
+
+  # Authorize access to the mounted UI (Sidekiq::Web / Flipper style).
+  # Returns truthy to allow. Defaults to development-only when nil.
+  # config.authenticate_with = ->(request) { request.session[:admin] }
+end

metadata

@@ -0,0 +1,103 @@
+--- !ruby/object:Gem::Specification
+name: bulletin-rb
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Charles Harris
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bullet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+description: Bulletin persists, fingerprints, and triages the N+1 / unused-eager-loading
+  / counter-cache warnings that Bullet detects, and exposes them through a mountable
+  Rails engine — Flipper UI / PgHero style, with a Sentry-style issue model.
+email:
+- charris000@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- MIT-LICENSE
+- README.md
+- app/controllers/bulletin/application_controller.rb
+- app/controllers/bulletin/issues_controller.rb
+- app/jobs/bulletin/prune_job.rb
+- app/jobs/bulletin/record_job.rb
+- app/models/bulletin/application_record.rb
+- app/models/bulletin/issue.rb
+- app/models/bulletin/occurrence.rb
+- app/views/bulletin/issues/index.html.erb
+- app/views/bulletin/issues/show.html.erb
+- app/views/layouts/bulletin/application.html.erb
+- config/routes.rb
+- db/migrate/20260527000001_create_bulletin_tables.rb
+- lib/bulletin-rb.rb
+- lib/bulletin.rb
+- lib/bulletin/configuration.rb
+- lib/bulletin/engine.rb
+- lib/bulletin/fingerprint.rb
+- lib/bulletin/middleware.rb
+- lib/bulletin/store.rb
+- lib/bulletin/store/active_record.rb
+- lib/bulletin/store/base.rb
+- lib/bulletin/store/null.rb
+- lib/bulletin/version.rb
+- lib/bulletin/warning.rb
+- lib/generators/bulletin/install_generator.rb
+- lib/generators/bulletin/templates/bulletin.rb
+homepage: https://github.com/charlesharris/bulletin-rb
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/charlesharris/bulletin-rb
+  source_code_uri: https://github.com/charlesharris/bulletin-rb
+  changelog_uri: https://github.com/charlesharris/bulletin-rb/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: A mountable UI that gives Bullet a memory.
+test_files: []