snitch-rails 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3c15ca6b5626013845df2ca3750b6b3233426c74a3bd0fe3b24e167b5da4cbd3
+  data.tar.gz: a641b8bc7ad9713d20c33cd7bd388a7d84371368e33c3f4dfaf5b383b94da267
+SHA512:
+  metadata.gz: d2ae2b490cc8ebecff6e82b4f73143e6937f482dfa478582bc94292e6d9e513f1c0a11ca40de50ec2b793dbad6097b088e604dd2ef2e220c1bdf655ac2e25cae
+  data.tar.gz: a2f09e55285231f04746b6917961bbab1832786b0dd8811a688449e8ec706716cb568aa6b5a01c383ff187a94eb02678ecae2b8a9f967fa51cf57e5ac9850896

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RiseKit
+
+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,78 @@
+# Snitch
+
+Snitch automatically catches unhandled exceptions in your Rails application, persists them to the database, and reports them as GitHub issues that @mention Claude for automated investigation.
+
+## Installation
+
+Add Snitch to your Gemfile:
+
+```ruby
+gem "snitch"
+```
+
+Run bundle install:
+
+```bash
+bundle install
+```
+
+Run the install generator to create the migration and initializer:
+
+```bash
+rails generate snitch:install
+```
+
+Run the migration:
+
+```bash
+rails db:migrate
+```
+
+## Configuration
+
+The generator creates an initializer at `config/initializers/snitch.rb`. Update it with your settings:
+
+```ruby
+Snitch.configure do |config|
+  # Required: GitHub personal access token with repo scope
+  config.github_token = ENV["SNITCH_GITHUB_TOKEN"]
+
+  # Required: GitHub repository in "owner/repo" format
+  config.github_repo = "your-org/your-repo"
+
+  # Who to @mention in GitHub issues (default: "@claude")
+  config.mention = "@claude"
+
+  # Enable/disable Snitch (default: true)
+  config.enabled = Rails.env.production?
+
+  # Exceptions to ignore (default: ActiveRecord::RecordNotFound, ActionController::RoutingError)
+  config.ignored_exceptions += [YourCustomError]
+end
+```
+
+### GitHub Token
+
+Create a [personal access token](https://github.com/settings/tokens) with the `repo` scope and set it as an environment variable:
+
+```bash
+export SNITCH_GITHUB_TOKEN=ghp_your_token_here
+```
+
+## How It Works
+
+1. Rack middleware catches any unhandled exception (and re-raises it so normal error handling still applies)
+2. The exception is fingerprinted using a SHA256 hash of the exception class and the first application backtrace line
+3. A `snitch_errors` record is created (or updated if the same fingerprint already exists, incrementing the occurrence count)
+4. An ActiveJob is enqueued to create a GitHub issue (or comment on the existing one for duplicate exceptions)
+5. The GitHub issue includes the full backtrace, request context, and an @mention for investigation
+
+## Requirements
+
+- Ruby >= 3.1
+- Rails >= 7.0
+- An ActiveJob backend (Sidekiq, GoodJob, etc.) for async GitHub reporting
+
+## License
+
+MIT

data/lib/generators/snitch/install/install_generator.rb

@@ -0,0 +1,21 @@
+require "rails/generators"
+require "rails/generators/active_record"
+
+module Snitch
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      def create_migration
+        migration_template "create_snitch_errors.rb.erb",
+          "db/migrate/create_snitch_errors.rb"
+      end
+
+      def create_initializer
+        template "snitch.rb", "config/initializers/snitch.rb"
+      end
+    end
+  end
+end

data/lib/generators/snitch/install/templates/create_snitch_errors.rb.erb

@@ -0,0 +1,22 @@
+class CreateSnitchErrors < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :snitch_errors do |t|
+      t.string :exception_class, null: false
+      t.text :message
+      t.text :backtrace
+      t.string :fingerprint, null: false
+      t.string :request_url
+      t.string :request_method
+      t.text :request_params
+      t.integer :occurrence_count, default: 1
+      t.integer :github_issue_number
+      t.string :github_issue_url
+      t.datetime :first_occurred_at
+      t.datetime :last_occurred_at
+      t.timestamps
+    end
+
+    add_index :snitch_errors, :fingerprint, unique: true
+    add_index :snitch_errors, :exception_class
+  end
+end

data/lib/generators/snitch/install/templates/snitch.rb

@@ -0,0 +1,16 @@
+Snitch.configure do |config|
+  # Required: GitHub personal access token
+  config.github_token = ENV["SNITCH_GITHUB_TOKEN"]
+
+  # Required: GitHub repository (owner/repo format)
+  config.github_repo = "owner/repo"
+
+  # Who to @mention in GitHub issues (default: "@claude")
+  # config.mention = "@claude"
+
+  # Enable/disable Snitch (default: true)
+  # config.enabled = Rails.env.production?
+
+  # Exceptions to ignore (default: RecordNotFound, RoutingError)
+  # config.ignored_exceptions += [CustomError]
+end

data/lib/snitch/configuration.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Snitch
+  class Configuration
+    attr_accessor :github_token, :github_repo, :mention, :enabled, :ignored_exceptions
+
+    def initialize
+      @github_token = nil
+      @github_repo = nil
+      @mention = "@claude"
+      @enabled = true
+      @ignored_exceptions = [
+        "ActiveRecord::RecordNotFound",
+        "ActionController::RoutingError"
+      ]
+    end
+  end
+end

data/lib/snitch/engine.rb

@@ -0,0 +1,9 @@
+module Snitch
+  class Engine < ::Rails::Engine
+    isolate_namespace Snitch
+
+    initializer "snitch.middleware" do |app|
+      app.middleware.insert_before 0, Snitch::Middleware
+    end
+  end
+end

data/lib/snitch/exception_handler.rb

@@ -0,0 +1,73 @@
+module Snitch
+  class ExceptionHandler
+    class << self
+      def handle(exception, env = {})
+        return unless Snitch.configuration.enabled
+        return if ignored?(exception)
+
+        fingerprint = Fingerprint.generate(exception)
+        request_data = extract_request_data(env)
+
+        record = find_or_create_record(exception, fingerprint, request_data)
+        enqueue_report(record)
+        record
+      end
+
+      private
+
+      def ignored?(exception)
+        Snitch.configuration.ignored_exceptions.any? do |ignored|
+          ignored_class = ignored.is_a?(String) ? ignored.safe_constantize : ignored
+          ignored_class && exception.is_a?(ignored_class)
+        end
+      end
+
+      def extract_request_data(env)
+        return {} if env.empty?
+        request = ActionDispatch::Request.new(env) rescue nil
+        return {} unless request
+
+        {
+          request_url: request.url,
+          request_method: request.method,
+          request_params: filtered_params(request)
+        }
+      end
+
+      def filtered_params(request)
+        request.filtered_parameters.to_json rescue request.params.to_json rescue "{}"
+      end
+
+      def find_or_create_record(exception, fingerprint, request_data)
+        existing = Event.find_by(fingerprint: fingerprint)
+
+        if existing
+          existing.update!(
+            occurrence_count: existing.occurrence_count + 1,
+            last_occurred_at: Time.current,
+            message: exception.message,
+            backtrace: exception.backtrace
+          )
+          existing
+        else
+          Event.create!(
+            exception_class: exception.class.name,
+            message: exception.message,
+            backtrace: exception.backtrace,
+            fingerprint: fingerprint,
+            occurrence_count: 1,
+            first_occurred_at: Time.current,
+            last_occurred_at: Time.current,
+            **request_data
+          )
+        end
+      end
+
+      def enqueue_report(record)
+        ReportExceptionJob.perform_later(record.id)
+      rescue => e
+        Rails.logger.error("[Snitch] Failed to enqueue report job: #{e.message}") if defined?(Rails)
+      end
+    end
+  end
+end

data/lib/snitch/fingerprint.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Snitch
+  module Fingerprint
+    module_function
+
+    def generate(exception)
+      app_line = first_app_backtrace_line(exception)
+      source = "#{exception.class.name}:#{app_line}"
+      Digest::SHA256.hexdigest(source)
+    end
+
+    def first_app_backtrace_line(exception)
+      return "" unless exception.backtrace
+
+      exception.backtrace.find { |line| app_line?(line) } || ""
+    end
+
+    def app_line?(line)
+      !line.include?("/gems/") && !line.include?("ruby/")
+    end
+  end
+end

data/lib/snitch/github_client.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "octokit"
+
+module Snitch
+  class GitHubClient
+    def initialize
+      @client = Octokit::Client.new(access_token: Snitch.configuration.github_token)
+      @repo = Snitch.configuration.github_repo
+    end
+
+    def create_issue(event)
+      title = build_title(event)
+      body = build_issue_body(event)
+
+      issue = @client.create_issue(@repo, title, body, labels: ["snitch", "bug"])
+
+      {
+        number: issue.number,
+        url: issue.html_url
+      }
+    end
+
+    def comment_on_issue(event)
+      body = build_comment_body(event)
+      @client.add_comment(@repo, event.github_issue_number, body)
+    end
+
+    private
+
+    def build_title(record)
+      msg = record.message.to_s.truncate(100)
+      "[Snitch] #{record.exception_class}: #{msg}"
+    end
+
+    def build_issue_body(record)
+      mention = Snitch.configuration.mention
+      <<~MARKDOWN
+        ## Exception Details
+        **Class:** `#{record.exception_class}`
+        **Message:** #{record.message}
+        **Occurrences:** #{record.occurrence_count}
+        **First seen:** #{record.first_occurred_at&.utc}
+
+        ## Backtrace
+        ```ruby
+        #{format_backtrace(record.backtrace)}
+        ```
+
+        ## Request Context
+        - **URL:** #{record.request_method} #{record.request_url}
+        - **Params:** `#{record.request_params}`
+
+        ---
+        #{mention} Please investigate this exception. Analyze the backtrace, identify the root cause, and suggest a fix.
+      MARKDOWN
+    end
+
+    def build_comment_body(record)
+      mention = Snitch.configuration.mention
+      <<~MARKDOWN
+        ## New Occurrence
+        **Total occurrences:** #{record.occurrence_count}
+        **Latest occurrence:** #{record.last_occurred_at&.utc}
+
+        ## Latest Request Context
+        - **URL:** #{record.request_method} #{record.request_url}
+        - **Params:** `#{record.request_params}`
+
+        ---
+        #{mention} This exception has occurred again. Please review if the previous analysis still applies.
+      MARKDOWN
+    end
+
+    def format_backtrace(backtrace)
+      return "No backtrace available" if backtrace.nil? || backtrace.empty?
+
+      lines = backtrace.is_a?(Array) ? backtrace : JSON.parse(backtrace) rescue [backtrace.to_s]
+      lines.first(20).join("\n")
+    end
+  end
+end

data/lib/snitch/jobs/report_exception_job.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Snitch
+  class ReportExceptionJob < ActiveJob::Base
+    queue_as :default
+
+    retry_on StandardError, wait: :polynomially_longer, attempts: 3
+
+    def perform(event_id)
+      record = Event.find_by(id: event_id)
+      return unless record
+
+      client = GitHubClient.new
+
+      if record.github_issue_number.present?
+        client.comment_on_issue(record)
+      else
+        result = client.create_issue(record)
+        record.update!(
+          github_issue_number: result[:number],
+          github_issue_url: result[:url]
+        )
+      end
+    end
+  end
+end

data/lib/snitch/middleware.rb

@@ -0,0 +1,18 @@
+module Snitch
+  class Middleware
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      @app.call(env)
+    rescue Exception => e
+      begin
+        ExceptionHandler.handle(e, env)
+      rescue => handler_error
+        Rails.logger.error("[Snitch] Handler error: #{handler_error.message}") if defined?(Rails)
+      end
+      raise e
+    end
+  end
+end

data/lib/snitch/models/event.rb

@@ -0,0 +1,13 @@
+module Snitch
+  class Event < ActiveRecord::Base
+    self.table_name = "snitch_errors"
+
+    serialize :backtrace, coder: JSON
+    serialize :request_params, coder: JSON
+
+    validates :exception_class, presence: true
+    validates :fingerprint, presence: true
+
+    scope :by_fingerprint, ->(fp) { where(fingerprint: fp) }
+  end
+end

data/lib/snitch/version.rb

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

data/lib/snitch.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "snitch/version"
+require "snitch/configuration"
+require "snitch/fingerprint"
+require "snitch/middleware"
+require "snitch/exception_handler"
+require "snitch/github_client"
+require "snitch/jobs/report_exception_job" if defined?(ActiveJob)
+require "snitch/engine" if defined?(Rails)
+
+module Snitch
+  class Error < StandardError; end
+
+  class << self
+    attr_writer :configuration
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def reset!
+      @configuration = Configuration.new
+    end
+  end
+end

metadata

@@ -0,0 +1,151 @@
+--- !ruby/object:Gem::Specification
+name: snitch-rails
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- RiseKit
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  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: octokit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: factory_bot_rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: faraday-retry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Snitch catches unhandled exceptions in your Rails app and opens GitHub
+  issues with full context.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/generators/snitch/install/install_generator.rb
+- lib/generators/snitch/install/templates/create_snitch_errors.rb.erb
+- lib/generators/snitch/install/templates/snitch.rb
+- lib/snitch.rb
+- lib/snitch/configuration.rb
+- lib/snitch/engine.rb
+- lib/snitch/exception_handler.rb
+- lib/snitch/fingerprint.rb
+- lib/snitch/github_client.rb
+- lib/snitch/jobs/report_exception_job.rb
+- lib/snitch/middleware.rb
+- lib/snitch/models/event.rb
+- lib/snitch/version.rb
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Automatic GitHub issue creation for unhandled Rails exceptions.
+test_files: []