devformance 0.1.0

data/config/puma.rb

@@ -0,0 +1,41 @@
+# This configuration file will be evaluated by Puma. The top-level methods that
+# are invoked here are part of Puma's configuration DSL. For more information
+# about methods provided by the DSL, see https://puma.io/puma/Puma/DSL.html.
+#
+# Puma starts a configurable number of processes (workers) and each process
+# serves each request in a thread from an internal thread pool.
+#
+# You can control the number of workers using ENV["WEB_CONCURRENCY"]. You
+# should only set this value when you want to run 2 or more workers. The
+# default is already 1.
+#
+# The ideal number of threads per worker depends both on how much time the
+# application spends waiting for IO operations and on how much you wish to
+# prioritize throughput over latency.
+#
+# As a rule of thumb, increasing the number of threads will increase how much
+# traffic a given process can handle (throughput), but due to CRuby's
+# Global VM Lock (GVL) it has diminishing returns and will degrade the
+# response time (latency) of the application.
+#
+# The default is set to 3 threads as it's deemed a decent compromise between
+# throughput and latency for the average Rails application.
+#
+# Any libraries that use a connection pool or another resource pool should
+# be configured to provide at least as many connections as the number of
+# threads. This includes Active Record's `pool` parameter in `database.yml`.
+threads_count = ENV.fetch("RAILS_MAX_THREADS", 3)
+threads threads_count, threads_count
+
+# Specifies the `port` that Puma will listen on to receive requests; default is 3000.
+port ENV.fetch("PORT", 3000)
+
+# Allow puma to be restarted by `bin/rails restart` command.
+plugin :tmp_restart
+
+# Run the Solid Queue supervisor inside of Puma for single-server deployments
+plugin :solid_queue if ENV["SOLID_QUEUE_IN_PUMA"]
+
+# Specify the PID file. Defaults to tmp/pids/server.pid in development.
+# In other environments, only set the PID file if requested.
+pidfile ENV["PIDFILE"] if ENV["PIDFILE"]

data/config/queue.yml

@@ -0,0 +1,22 @@
+default: &default
+  dispatchers:
+    - polling_interval: 1
+      batch_size: 500
+  workers:
+    - queues: [devformance]
+      threads: 10
+      processes: 1
+      polling_interval: 0.1
+    - queues: "*"
+      threads: 3
+      processes: <%= ENV.fetch("JOB_CONCURRENCY", 1) %>
+      polling_interval: 0.1
+
+development:
+  <<: *default
+
+test:
+  <<: *default
+
+production:
+  <<: *default

data/config/recurring.yml

@@ -0,0 +1,15 @@
+# examples:
+#   periodic_cleanup:
+#     class: CleanSoftDeletedRecordsJob
+#     queue: background
+#     args: [ 1000, { batch_size: 500 } ]
+#     schedule: every hour
+#   periodic_cleanup_with_command:
+#     command: "SoftDeletedRecord.due.delete_all"
+#     priority: 2
+#     schedule: at 5am every day
+
+production:
+  clear_solid_queue_finished_jobs:
+    command: "SolidQueue::Job.clear_finished_in_batches(sleep_between_batches: 0.3)"
+    schedule: every hour at minute 12

data/config/routes.rb

@@ -0,0 +1,20 @@
+Rails.application.routes.draw do
+  scope "/devformance", module: "devformance", as: "devformance" do
+    root "metrics#index"
+
+    post "run_tests",                            to: "metrics#run_tests"
+    get  "runs/:run_id/status",                  to: "metrics#run_status"
+    get  "runs/:run_id/logs/:file_key/download", to: "metrics#download_log"
+
+    get  "playground",     to: "playground#run"
+    post "playground/run", to: "playground#run"
+
+    get "icon.svg", to: "icons#svg"
+    get "icon.png", to: "icons#png"
+  end
+
+  get "/", to: redirect("/devformance")
+  get "/up", to: "rails/health#show"
+
+  mount ActionCable.server => "/devformance/cable"
+end

data/config/storage.yml

@@ -0,0 +1,34 @@
+test:
+  service: Disk
+  root: <%= Rails.root.join("tmp/storage") %>
+
+local:
+  service: Disk
+  root: <%= Rails.root.join("storage") %>
+
+# Use bin/rails credentials:edit to set the AWS secrets (as aws:access_key_id|secret_access_key)
+# amazon:
+#   service: S3
+#   access_key_id: <%= Rails.application.credentials.dig(:aws, :access_key_id) %>
+#   secret_access_key: <%= Rails.application.credentials.dig(:aws, :secret_access_key) %>
+#   region: us-east-1
+#   bucket: your_own_bucket-<%= Rails.env %>
+
+# Remember not to checkin your GCS keyfile to a repository
+# google:
+#   service: GCS
+#   project: your_project
+#   credentials: <%= Rails.root.join("path/to/gcs.keyfile") %>
+#   bucket: your_own_bucket-<%= Rails.env %>
+
+# Use bin/rails credentials:edit to set the Azure Storage secret (as azure_storage:storage_access_key)
+# microsoft:
+#   service: AzureStorage
+#   storage_account_name: your_account_name
+#   storage_access_key: <%= Rails.application.credentials.dig(:azure_storage, :storage_access_key) %>
+#   container: your_container_name-<%= Rails.env %>
+
+# mirror:
+#   service: Mirror
+#   primary: local
+#   mirrors: [ amazon, google, microsoft ]

data/db/migrate/20260317144616_create_slow_queries.rb

@@ -0,0 +1,13 @@
+class CreateSlowQueries < ActiveRecord::Migration[7.2]
+  def change
+    unless table_exists?(:slow_queries)
+      create_table :slow_queries do |t|
+        t.string  :model_class
+        t.integer :line_number
+        t.text    :fix_suggestion
+
+        t.timestamps
+      end
+    end
+  end
+end

data/db/migrate/20260317175630_create_performance_runs.rb

@@ -0,0 +1,14 @@
+class CreatePerformanceRuns < ActiveRecord::Migration[7.2]
+  def change
+    unless table_exists?(:performance_runs)
+      create_table :performance_runs do |t|
+        t.string :run_id
+        t.integer :total_files
+        t.integer :completed_files
+        t.string :status
+
+        t.timestamps
+      end
+    end
+  end
+end

data/db/migrate/20260317195043_add_run_id_to_slow_queries.rb

@@ -0,0 +1,10 @@
+class AddRunIdToSlowQueries < ActiveRecord::Migration[7.2]
+  def change
+    unless column_exists?(:slow_queries, :run_id)
+      add_column :slow_queries, :run_id, :string
+    end
+    unless index_exists?(:slow_queries, :run_id)
+      add_index :slow_queries, :run_id
+    end
+  end
+end

data/db/migrate/20260319000001_create_devformance_runs.rb

@@ -0,0 +1,20 @@
+class CreateDevformanceRuns < ActiveRecord::Migration[7.2]
+  def change
+    unless table_exists?(:devformance_runs)
+      create_table :devformance_runs do |t|
+        t.string   :run_id,          null: false
+        t.integer  :status,          default: 0, null: false
+        t.datetime :started_at
+        t.datetime :finished_at
+        t.integer  :total_files,     default: 0
+        t.integer  :completed_files, default: 0
+
+        t.timestamps
+      end
+
+      unless index_exists?(:devformance_runs, :run_id)
+        add_index :devformance_runs, :run_id, unique: true
+      end
+    end
+  end
+end

data/db/migrate/20260319000002_create_devformance_file_results.rb

@@ -0,0 +1,29 @@
+class CreateDevformanceFileResults < ActiveRecord::Migration[7.2]
+  def change
+    unless table_exists?(:devformance_file_results)
+      create_table :devformance_file_results do |t|
+        t.string  :run_id,           null: false
+        t.string  :file_key,         null: false
+        t.string  :file_path
+        t.integer :status,           default: 0, null: false
+        t.integer :total_tests,      default: 0
+        t.integer :passed_tests,     default: 0
+        t.integer :failed_tests,     default: 0
+        t.integer :slow_query_count, default: 0
+        t.integer :n1_count,         default: 0
+        t.float   :coverage
+        t.integer :duration_ms
+        t.string  :log_path
+
+        t.timestamps
+      end
+
+      unless index_exists?(:devformance_file_results, :run_id)
+        add_index :devformance_file_results, :run_id
+      end
+      unless index_exists?(:devformance_file_results, [ :run_id, :file_key ])
+        add_index :devformance_file_results, [ :run_id, :file_key ], unique: true
+      end
+    end
+  end
+end

data/db/migrate/20260319000003_add_columns_to_slow_queries.rb

@@ -0,0 +1,7 @@
+class AddColumnsToSlowQueries < ActiveRecord::Migration[7.2]
+  def change
+    add_column :slow_queries, :sql, :text unless column_exists?(:slow_queries, :sql)
+    add_column :slow_queries, :duration_ms, :float unless column_exists?(:slow_queries, :duration_ms)
+    add_column :slow_queries, :file_key, :string unless column_exists?(:slow_queries, :file_key)
+  end
+end

data/lib/devformance/bullet_log_parser.rb

@@ -0,0 +1,47 @@
+module Devformance
+  module BulletLogParser
+    Warning = Data.define(:type, :endpoint, :model_class, :associations, :fix_suggestion, :line_number, :call_stack)
+
+    BLOCK_START = /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}\[WARN\]/
+
+    def self.parse(content)
+      blocks = content.split(BLOCK_START).map(&:strip).reject(&:empty?)
+      blocks.filter_map { |block| parse_block(block) }
+    end
+
+    def self.parse_block(block)
+      lines = block.lines.map(&:chomp)
+
+      endpoint     = lines.find { |l| l.match?(/^(GET|POST|PUT|PATCH|DELETE|HEAD)\s+/) }&.strip
+      type_line    = lines.find { |l| l.include?("eager loading detected") }
+      model_line   = lines.find { |l| l.match?(/\w+ => \[/) }
+      fix_line     = lines.find { |l| l.include?("Add to your query") || l.include?("Remove from your query") }
+
+      return nil unless type_line && model_line
+
+      type = type_line.strip.start_with?("USE") ? :add_eager_load : :remove_eager_load
+
+      model_class  = model_line.match(/^\s*(\w+)\s*=>/)[1] rescue nil
+      associations = model_line.match(/=>\s*(\[.+\])/)[1] rescue nil
+
+      fix_suggestion = fix_line&.strip
+
+      call_stack_start = lines.index { |l| l.strip == "Call stack" }
+      call_stack = call_stack_start ? lines[(call_stack_start + 1)..].map(&:strip).reject(&:empty?) : []
+
+      app_line = call_stack.find { |l| !l.include?("/gems/") && !l.include?("/ruby/") && l.match?(/\.rb:\d+/) }
+      line_number = app_line&.match(/:(\d+):/)&.[](1)&.to_i
+
+      Warning.new(
+        type:          type,
+        endpoint:      endpoint,
+        model_class:   model_class,
+        associations:  associations,
+        fix_suggestion: fix_suggestion,
+        line_number:   line_number,
+        call_stack:    call_stack
+      )
+    end
+    private_class_method :parse_block
+  end
+end

data/lib/devformance/compatibility.rb

@@ -0,0 +1,12 @@
+module Devformance
+  module Compatibility
+    def self.importmap?    = defined?(::Importmap::Engine)
+    def self.turbo?        = defined?(::Turbo::Engine)
+    def self.stimulus?     = defined?(::Stimulus::Engine)
+    def self.propshaft?    = defined?(::Propshaft::Engine)
+    def self.bullet?       = defined?(::Bullet)
+    def self.solid_cable?  = defined?(::SolidCable)
+    def self.hotwire?      = turbo? && stimulus? && importmap?
+    def self.rails_version = Gem::Version.new(Rails.version)
+  end
+end

data/lib/devformance/coverage_setup.rb

@@ -0,0 +1,33 @@
+require "simplecov"
+
+module Devformance
+  class CoverageSetup
+    def self.start
+      return unless ENV["COVERAGE"] == "true" || ENV["SIMPLECOV"] == "true"
+
+      SimpleCov.start do
+        add_filter "/vendor/"
+        add_filter "/spec/"
+
+        unless ENV["DEVMETRICS_INCLUDE_TESTS"] == "true"
+          add_filter "/test/"
+        end
+
+        add_filter "/config/"
+        add_filter "/db/"
+
+        minimum_coverage Devformance.configuration.coverage_minimum_coverage || 80
+
+        coverage_dir Devformance.configuration.coverage_dir || "coverage"
+      end
+    end
+
+    def self.result
+      SimpleCov.result
+    end
+
+    def self.pct
+      SimpleCov.result&.covered_percent&.round(1)
+    end
+  end
+end

data/lib/devformance/engine.rb

@@ -0,0 +1,80 @@
+module Devformance
+  class Engine < ::Rails::Engine
+    isolate_namespace Devformance
+
+    config.static_assets = true
+
+    # Use a dedicated routes file so config/routes.rb can be the host-app routes
+    paths["config/routes.rb"] = "config/engine_routes.rb"
+
+    config.to_prepare do
+      Devformance::ApplicationController.layout "devformance/application"
+
+      require "devformance/log_writer"
+      require "devformance/sql_instrumentor"
+      require "devformance/run_orchestrator"
+      require "devformance/bullet_log_parser"
+
+      # Explicitly require and alias channel for ActionCable/Solid Cable
+      # ActionCable uses constantize which needs the class to be loadable
+      begin
+        require "devformance/metrics_channel"
+      rescue LoadError
+        # Already loaded via autoload
+      end
+
+      unless ::Object.const_defined?(:DevformanceChannel)
+        ::Object.const_set(:DevformanceChannel, Devformance::MetricsChannel)
+      end
+      unless ::Object.const_defined?(:MetricsChannel)
+        ::Object.const_set(:MetricsChannel, Devformance::MetricsChannel)
+      end
+    end
+
+    # ── Asset & View configuration ───────────────────────────────────────────
+    initializer "devformance.importmap", after: "importmap" do |app|
+      if app.config.respond_to?(:importmap)
+        app.config.importmap.paths << root.join("config/importmap.rb")
+        app.config.importmap.cache_sweepers << root.join("app/javascript")
+      end
+    end
+
+    # ── Action View Helpers ──────────────────────────────────────────────────
+    initializer "devformance.helpers" do
+      ActiveSupport.on_load(:action_view) do
+        if defined?(::Importmap::ImportmapTagsHelper)
+          include ::Importmap::ImportmapTagsHelper
+        end
+
+        if defined?(::Turbo::FramesHelper)
+          include ::Turbo::FramesHelper
+        end
+      end
+    end
+
+    initializer "devformance.assets" do |app|
+      if app.config.respond_to?(:assets)
+        app.config.assets.paths << root.join("app/assets/stylesheets")
+        app.config.assets.paths << root.join("app/assets/javascripts")
+        app.config.assets.paths << root.join("app/assets/images")
+        app.config.assets.paths << root.join("app/javascript")
+        unless defined?(::Propshaft)
+          app.config.assets.precompile += %w[devformance/application.js devformance/dashboard.css icon.svg icon.png]
+        end
+      end
+    end
+
+    initializer "devformance.sql_notifications" do
+      ActiveSupport::Notifications.subscribe("sql.active_record") do |*args|
+        event = ActiveSupport::Notifications::Event.new(*args)
+        Devformance::SqlInstrumentor.record(event) if defined?(Devformance::SqlInstrumentor)
+      end
+    end
+
+    config.after_initialize do
+      if ENV["DEVMETRICS_SKIP_DB_SETUP"] == "1"
+        Rails.logger.info "[Devformance] Database setup skipped for test runs"
+      end
+    end
+  end
+end

data/lib/devformance/log_writer.rb

@@ -0,0 +1,29 @@
+module Devformance
+  class LogWriter
+    LOG_BASE = -> { Rails.root.join("log", "devformance", "runs") }
+
+    def self.open(run_id, file_key)
+      dir = LOG_BASE.call.join(run_id.to_s)
+      FileUtils.mkdir_p(dir)
+      new(dir.join("#{file_key}.log"))
+    end
+
+    def initialize(path)
+      @path = path
+      @file = File.open(path, "w")
+    end
+
+    def write(line)
+      @file.puts(line)
+      @file.flush
+    end
+
+    def close
+      @file.close
+    end
+
+    def path
+      @path.to_s
+    end
+  end
+end

data/lib/devformance/run_orchestrator.rb

@@ -0,0 +1,58 @@
+module Devformance
+  class RunOrchestrator
+    def self.call(framework: nil)
+      new(framework: framework).call
+    end
+
+    def initialize(framework: nil)
+      @framework = framework || detect_framework
+    end
+
+    def call
+      file_paths = @framework.discover_files
+      if file_paths.empty?
+        return { error: "No test files found matching #{@framework.file_pattern}" }
+      end
+
+      tagged = file_paths.select { |f| File.read(f).match?(/devformance/i) }
+      file_paths = tagged if tagged.any?
+
+      run = ::Devformance::Run.create_for_files(file_paths)
+
+      file_metas = file_paths.map do |path|
+        file_key = ::Devformance::FileResult.file_key_for(path)
+        ::Devformance::FileResult.create!(
+          run_id:     run.run_id,
+          file_key:   file_key,
+          file_path:  path,
+          status:     :pending
+        )
+        { file_key: file_key, file_path: path, display_name: path.sub(Rails.root.to_s + "/", "") }
+      end
+
+      ActionCable.server.broadcast(
+        "devformance:run:#{run.run_id}",
+        { type: "run_started", run_id: run.run_id, files: file_metas, framework: @framework.name }
+      )
+
+      file_metas.each do |meta|
+        ::Devformance::FileRunnerJob.perform_later(
+          run_id:    run.run_id,
+          file_path: meta[:file_path],
+          file_key:  meta[:file_key],
+          framework: @framework.name
+        )
+      end
+
+      { run_id: run.run_id, file_count: file_metas.size, files: file_metas, framework: @framework.name }
+    end
+
+    private
+
+    def detect_framework
+      Devformance.configuration.framework_adapter ||
+        Devformance::TestFramework::Detector.detect(Rails.root) ||
+        Devformance::TestFramework::RSpec.new(Rails.root)
+    end
+  end
+end

data/lib/devformance/sql_instrumentor.rb

@@ -0,0 +1,29 @@
+module Devformance
+  class SqlInstrumentor
+    THREAD_KEY = :devformance_sql_collector
+
+    def self.around_run
+      Thread.current[THREAD_KEY] = { queries: [], start: Time.current }
+      yield
+    ensure
+      Thread.current[THREAD_KEY] = nil
+    end
+
+    def self.record(event)
+      collector = Thread.current[THREAD_KEY]
+      return unless collector
+
+      ms  = event.duration.round(2)
+      sql = event.payload[:sql].to_s.strip
+
+      return if sql.match?(/\A(BEGIN|COMMIT|ROLLBACK|SAVEPOINT|RELEASE)/i)
+
+      collector[:queries] << { sql: sql, ms: ms, at: Time.current.iso8601 }
+      collector[:queries].last
+    end
+
+    def self.queries
+      Thread.current[THREAD_KEY]&.dig(:queries) || []
+    end
+  end
+end

data/lib/devformance/test_framework/base.rb

@@ -0,0 +1,43 @@
+module Devformance
+  module TestFramework
+    class Base
+      attr_reader :root_path
+
+      def initialize(root_path)
+        @root_path = root_path
+      end
+
+      def discover_files
+        raise NotImplementedError, "#{self.class} must implement #discover_files"
+      end
+
+      def run_command(file_path)
+        raise NotImplementedError, "#{self.class} must implement #run_command"
+      end
+
+      def parse_summary(output)
+        raise NotImplementedError, "#{self.class} must implement #parse_summary"
+      end
+
+      def classify_line(line)
+        raise NotImplementedError, "#{self.class} must implement #classify_line"
+      end
+
+      def file_pattern
+        raise NotImplementedError, "#{self.class} must implement #file_pattern"
+      end
+
+      def name
+        raise NotImplementedError, "#{self.class} must implement #name"
+      end
+
+      def available?
+        !discover_files.empty?
+      end
+
+      def runner_command
+        raise NotImplementedError, "#{self.class} must implement #runner_command"
+      end
+    end
+  end
+end

data/lib/devformance/test_framework/coverage_helper.rb

@@ -0,0 +1,76 @@
+module Devformance
+  module TestFramework
+    module CoverageHelper
+      def self.setup_simplecov
+        return unless defined?(SimpleCov)
+
+        SimpleCov.start do
+          add_filter "/vendor/"
+          add_filter "/spec/"
+          add_filter "/test/"
+          add_filter "/config/"
+          add_filter "/db/"
+
+          minimum_coverage Devformance.configuration.coverage_minimum_coverage || 80
+        end
+      end
+
+      def self.run_with_coverage(file_path, framework_name)
+        if framework_name == "RSpec"
+          run_rspec_with_coverage(file_path)
+        elsif framework_name == "Minitest"
+          run_minitest_with_coverage(file_path)
+        else
+          raise "Unsupported framework: #{framework_name}"
+        end
+      end
+
+      def self.run_rspec_with_coverage(file_path)
+        require "simplecov"
+        SimpleCov.start do
+          add_filter "/vendor/"
+          add_filter "/spec/"
+        end
+
+        require "rspec/core"
+        exit_code = RSpec::Core::Runner.run([ file_path, "--format", "progress" ])
+        { exit_code: exit_code, coverage: SimpleCov.result }
+      end
+
+      def self.run_minitest_with_coverage(file_path)
+        require "simplecov"
+        SimpleCov.start do
+          add_filter "/vendor/"
+          add_filter "/test/"
+        end
+
+        require "rails/test_help"
+        require "minitest/autorun"
+        Minitest.run
+      end
+
+      def self.parse_coverage_json
+        resultset_path = Rails.root.join(Devformance.configuration.coverage_dir || "coverage", ".resultset.json")
+        return nil unless File.exist?(resultset_path)
+
+        JSON.parse(File.read(resultset_path))
+      rescue JSON::ParserError
+        nil
+      end
+
+      def self.calculate_coverage_pct(resultset, file_path)
+        return nil unless resultset
+
+        rel_path = file_path.sub(Rails.root.to_s + "/", "")
+        all_lines = resultset.values.flat_map do |r|
+          r.dig("coverage", rel_path)&.compact || []
+        end.compact
+
+        return nil if all_lines.empty?
+
+        covered = all_lines.count { |v| v.to_i > 0 }
+        (covered.to_f / all_lines.size * 100).round(1)
+      end
+    end
+  end
+end

data/lib/devformance/test_framework/detector.rb

@@ -0,0 +1,26 @@
+require_relative "rspec"
+require_relative "minitest"
+
+module Devformance
+  module TestFramework
+    class Detector
+      FRAMEWORKS = [ RSpec, Minitest ].freeze
+
+      def self.detect(root_path)
+        FRAMEWORKS.each do |framework_class|
+          adapter = framework_class.new(root_path)
+          return adapter if adapter.available?
+        end
+        nil
+      end
+
+      def self.all
+        FRAMEWORKS
+      end
+
+      def self.for_name(name)
+        FRAMEWORKS.find { |f| f.name == name }
+      end
+    end
+  end
+end