constable-rails 0.1.0

data/lib/constable/selection.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+module Constable
+  # Decides what a given `constable test` invocation actually runs.
+  #
+  # The default with no arguments is deliberately *not* the whole suite: locally, the
+  # interesting tests are the ones covering what you just changed, so the default is
+  # git-diff scoped. CI passes --full and gets everything, every time. When git can't
+  # answer -- no repo, no commits, a detached checkout -- the answer is the full suite
+  # rather than a confidently empty one. Running too much is a slow day; running too
+  # little is a false green.
+  class Selection
+    # A single resolved target: a file, optionally narrowed to one investigation by line.
+    Target = Struct.new(:path, :line, :kind, keyword_init: true) do
+      def native? = kind == :native
+      def cold?   = kind == :cold
+      def to_s    = line ? "#{path}:#{line}" : path.to_s
+    end
+
+    NATIVE_GLOBS = [
+      "test/cases/**/*.rb",
+      "spec/cases/**/*.rb",
+      "test/**/*_case.rb",
+      "spec/**/*_case.rb"
+    ].freeze
+
+    attr_reader :config, :root, :args, :reason
+
+    def initialize(args = [], config: Constable.config, root: Constable.root,
+                   full: false, unsafe_only: false, tier: nil)
+      @args        = Array(args)
+      @config      = config
+      @root        = root.to_s
+      @full        = full
+      @unsafe_only = unsafe_only
+      @tier        = tier&.to_sym
+      @reason      = nil
+    end
+
+    def full?        = @full
+    def unsafe_only? = @unsafe_only
+
+    # => [Target]
+    def targets
+      @targets ||= begin
+        list =
+          if @args.any?
+            explicit_targets
+          elsif @unsafe_only
+            cold_targets
+          elsif @full
+            all_targets
+          else
+            diff_targets
+          end
+
+        list = list.select(&:cold?) if @unsafe_only
+        list = list.select { |t| tier_matches?(t) } if @tier
+        list.uniq { |t| [t.path, t.line] }
+      end
+    end
+
+    def native_targets = targets.select(&:native?)
+    def cold_targets_selected = targets.select(&:cold?)
+    def empty? = targets.empty?
+
+    # A specific investigation was named (PATH:LINE), so only that one should run.
+    def line_filter_for(path)
+      targets.select { |t| t.path == path && t.line }.map(&:line)
+    end
+
+    private
+
+    # "spec/cases/sessions_case.rb:12" -- a file, or one investigation inside it.
+    def explicit_targets
+      @reason = "explicit paths"
+      @args.flat_map do |arg|
+        path, line = split_line(arg)
+        absolute = absolutize(path)
+
+        if File.directory?(absolute)
+          files_under(absolute).map { |f| target_for(f, nil) }
+        else
+          [target_for(absolute, line)]
+        end
+      end.compact
+    end
+
+    def all_targets
+      @reason = "full suite"
+      (native_files + cold_files).map { |f| target_for(f, nil) }.compact
+    end
+
+    def cold_targets
+      @reason = "cold cases only"
+      cold_files.map { |f| Target.new(path: f, line: nil, kind: :cold) }
+    end
+
+    # Changed files map to their own case files plus any case file that looks like it
+    # covers them (app/models/user.rb -> **/user_case.rb, **/users_*_case.rb).
+    def diff_targets
+      unless Diff.available?(root: @root)
+        @reason = "full suite (git unavailable)"
+        return all_targets
+      end
+
+      changed = Diff.changed_files(root: @root)
+      if changed.empty?
+        @reason = "full suite (no changes detected)"
+        return all_targets
+      end
+
+      matched = changed.flat_map { |file| cases_covering(file) }.uniq
+      if matched.empty?
+        @reason = "full suite (no cases matched the diff)"
+        return all_targets
+      end
+
+      @reason = "#{matched.size} #{matched.size == 1 ? "case" : "cases"} touched by the diff"
+      matched.map { |f| target_for(f, nil) }.compact
+    end
+
+    # Maps one changed source file to the case files that plausibly exercise it. A changed
+    # test file is itself a target; a changed app file is matched by name.
+    def cases_covering(changed_file)
+      absolute = absolutize(changed_file)
+      known = native_files + cold_files
+      return [absolute] if known.include?(absolute)
+
+      stem = File.basename(changed_file, ".rb")
+      return [] if stem.empty?
+
+      singular = stem.sub(/s\z/, "")
+      known.select do |case_file|
+        base = File.basename(case_file, ".rb")
+        base.start_with?(stem) || base.start_with?(singular) ||
+          base.sub(/_(case|spec|test)\z/, "") == stem
+      end
+    end
+
+    def target_for(file, line)
+      return nil unless File.file?(file)
+
+      Target.new(path: file, line: line, kind: kind_of(file))
+    end
+
+    def kind_of(file)
+      return :cold if @config.cold_case?(file)
+      return :cold if cold_by_content?(file)
+
+      :native
+    end
+
+    # A file that declares itself a ColdCase is one, whatever the globs say.
+    def cold_by_content?(file)
+      head = File.foreach(file).first(40).join
+      head.include?("Constable::ColdCase")
+    rescue StandardError
+      false
+    end
+
+    def native_files
+      @native_files ||= glob(NATIVE_GLOBS).reject { |f| @config.cold_case?(f) }
+    end
+
+    def cold_files
+      @cold_files ||= begin
+        from_config = glob(@config.cold_cases)
+        declared = glob(["test/**/*_spec.rb", "spec/**/*_spec.rb", "test/**/*_test.rb"])
+                   .select { |f| cold_by_content?(f) }
+        (from_config + declared).uniq
+      end
+    end
+
+    def files_under(dir)
+      Dir.glob(File.join(dir, "**", "*.rb"))
+    end
+
+    def glob(patterns)
+      Array(patterns).flat_map { |p| Dir.glob(File.join(@root, p.to_s)) }
+                     .select { |f| File.file?(f) }
+                     .sort
+                     .uniq
+    end
+
+    def tier_matches?(target)
+      return true unless @tier
+
+      @config.tier_for(target.path) == @tier
+    end
+
+    # "path/to/file.rb:12" -> ["path/to/file.rb", 12]
+    def split_line(arg)
+      if (match = arg.to_s.match(/\A(.*?):(\d+)\z/))
+        [match[1], match[2].to_i]
+      else
+        [arg.to_s, nil]
+      end
+    end
+
+    def absolutize(path)
+      File.absolute_path?(path) ? path : File.expand_path(path, @root)
+    end
+  end
+end

data/lib/constable/storage/adapter.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Constable
+  module Storage
+    # The pluggable storage interface -- "the blotter".
+    #
+    # All operational data (flake history, jail/parole state, warrants) lives in a store
+    # Constable owns entirely. Never the app's real database, and never the app's
+    # transactional test connection, for three reasons:
+    #
+    #   1. Native cases wrap each test in a rolled-back transaction. Writing through the
+    #      app's connection would roll this data back along with everything else.
+    #   2. :unit-tier runs skip booting the Rails/DB stack for speed. Requiring a live
+    #      Postgres just to record "did this test pass" would undo that.
+    #   3. The workload is a handful of tables and ~one row per test per run. It does not
+    #      need a client-server database.
+    #
+    # Adapters must be safe to open from the parent process; workers never write. Results
+    # travel back over a pipe and the parent is the only writer, which keeps every adapter
+    # free of cross-process write contention.
+    class Adapter
+      class NotSupported < StandardError; end
+
+      attr_reader :config
+
+      def initialize(config)
+        @config = config
+      end
+
+      def self.build(config)
+        case config.storage_adapter.to_s
+        when "sqlite", "sqlite3", nil, "" then SqliteAdapter.new(config)
+        when "postgres", "postgresql"     then PostgresAdapter.new(config)
+        when "mysql", "mysql2"            then MysqlAdapter.new(config)
+        else
+          raise ArgumentError, "unknown storage adapter #{config.storage_adapter.inspect} " \
+                               "(expected one of: sqlite, postgres, mysql)"
+        end
+      end
+
+      # --- lifecycle -------------------------------------------------------------
+      def setup!    = raise(NotImplementedError, "#{self.class}#setup!")
+      def close     = nil
+      def reset!    = raise(NotImplementedError, "#{self.class}#reset!")
+
+      # --- runs ------------------------------------------------------------------
+      def start_run(seed:, mode:, full:) = raise(NotImplementedError)
+      def finish_run(run_id, totals:)    = raise(NotImplementedError)
+      def runs(limit: 30)                = raise(NotImplementedError)
+
+      # --- flake history ---------------------------------------------------------
+      # Every test's pass/fail result is recorded, native and cold alike.
+      def record_result(run_id, result)          = raise(NotImplementedError)
+      def history_for(identity, limit: 50)       = raise(NotImplementedError)
+      def last_status(identity)                  = raise(NotImplementedError)
+      def known_identities                       = raise(NotImplementedError)
+      # Native-vs-cold counts per run, newest run first. Backs the trend in `constable
+      # status`, which is the one place the split between the two matters over time.
+      def kind_totals(limit: 30)                 = raise(NotImplementedError)
+      def relink(old_identity, new_identity)     = raise(NotImplementedError)
+
+      # --- jail docket -----------------------------------------------------------
+      def jail(identity, label:, file:, line:, reason:) = raise(NotImplementedError)
+      def jailed                                          = raise(NotImplementedError)
+      def jail_entry(identity)                            = raise(NotImplementedError)
+      def jailed?(identity)                               = !jail_entry(identity).nil?
+      def parole(identity)                                = raise(NotImplementedError)
+      def release(identity)                               = raise(NotImplementedError)
+      def record_parole_pass(identity)                    = raise(NotImplementedError)
+      def record_parole_violation(identity)               = raise(NotImplementedError)
+      def paroled                                         = raise(NotImplementedError)
+
+      # --- warrants --------------------------------------------------------------
+      def issue_warrant(identity, label:, file:, line:, reason: nil) = raise(NotImplementedError)
+      def warrants                                                   = raise(NotImplementedError)
+      def warrant_entry(identity)                                    = raise(NotImplementedError)
+      def warranted?(identity)                                       = !warrant_entry(identity).nil?
+      def clear_warrant(identity)                                    = raise(NotImplementedError)
+      def touch_warrant(identity, cleared:)                          = raise(NotImplementedError)
+
+      # --- durations (worker load balancing, slowest list) -----------------------
+      def record_duration(identity, duration)  = raise(NotImplementedError)
+      def duration_index                       = raise(NotImplementedError)
+      def slowest(limit: 10)                   = raise(NotImplementedError)
+
+      # --- coverage --------------------------------------------------------------
+      def record_coverage(run_id, percent:, files:) = raise(NotImplementedError)
+      def coverage_trend(limit: 30)                 = raise(NotImplementedError)
+    end
+  end
+end

data/lib/constable/storage/mysql_adapter.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require "uri"
+require "constable/storage"
+
+module Constable
+  module Storage
+    # Optional blotter, same trade-off as the Postgres adapter: worth it only when one
+    # store has to be shared across many CI machines. Locally, SQLite wins on every axis.
+    #
+    # == A separate connection, always
+    #
+    # This adapter opens its *own* connection from +storage.url+ and never borrows
+    # ActiveRecord's. The reasoning is the same as everywhere else in the storage layer:
+    #
+    #   1. Native cases run inside a transaction that is rolled back after every test.
+    #      Writing the blotter through the app's connection would roll the blotter back
+    #      too, and flake history would never survive a run.
+    #   2. :unit-tier runs never boot the DB stack, so there may be no app connection at
+    #      all to borrow.
+    #   3. Reloading the app's test schema must never take the jail docket with it.
+    #
+    # The +mysql2+ gem is not a dependency of constable-rails; it is required lazily so
+    # nobody installs a driver they do not use.
+    class MysqlAdapter < RelationalAdapter
+      # MySQL's "index already exists". CREATE INDEX has no IF NOT EXISTS in MySQL, so an
+      # idempotent setup! means creating and forgiving the duplicate.
+      DUPLICATE_INDEX = 1061
+
+      def close
+        @connection&.close
+        super
+      rescue StandardError
+        super
+      end
+
+      private
+
+      def connect!
+        # Config first, driver second: a missing url is a typo in config.yml and worth
+        # saying so before we go looking for a gem.
+        url = config.storage_url
+        if url.nil? || url.to_s.empty?
+          raise Constable::ConfigurationError,
+                "storage.adapter is \"mysql\" but storage.url is not set in .constable/config.yml " \
+                "(expected something like mysql2://user:pass@host/constable_metadata -- and it must " \
+                "point at a database separate from your app's, never the app's test database)"
+        end
+
+        require_driver!
+
+        # Deliberately Mysql2::Client and not ActiveRecord: this connection lives outside
+        # the app's rolled-back test transaction. See the class comment.
+        @connection = Mysql2::Client.new(**connection_options(url.to_s))
+      end
+
+      def require_driver!
+        require "mysql2"
+      rescue LoadError => e
+        raise Constable::ConfigurationError,
+              "the mysql2 gem is required for Constable's mysql storage adapter " \
+              "(add `gem \"mysql2\"` to your Gemfile and run `bundle install`, or set " \
+              "storage.adapter back to \"sqlite\" in .constable/config.yml) -- #{e.message}"
+      end
+
+      def connection_options(url)
+        uri = URI.parse(url)
+        {
+          host: uri.host || "127.0.0.1",
+          port: uri.port || 3306,
+          username: uri.user && URI.decode_www_form_component(uri.user),
+          password: uri.password && URI.decode_www_form_component(uri.password),
+          database: uri.path.to_s.delete_prefix("/"),
+          cast_booleans: false,
+          reconnect: true
+        }.compact
+      end
+
+      def types
+        super.merge(
+          pk: "BIGINT AUTO_INCREMENT PRIMARY KEY",
+          int: "BIGINT",
+          float: "DOUBLE"
+        )
+      end
+
+      def create_index(name, table, columns)
+        execute_raw("CREATE INDEX #{name} ON #{table} (#{columns.join(", ")})")
+      rescue StandardError => e
+        # Mysql2::Error::ConnectionError et al. all respond to #error_number.
+        raise unless e.respond_to?(:error_number) && e.error_number == DUPLICATE_INDEX
+      end
+
+      def execute_raw(sql)
+        connection.query(sql)
+        nil
+      end
+
+      def query(sql, binds = [])
+        return connection.query(sql).to_a if binds.empty?
+
+        connection.prepare(sql).execute(*binds).to_a
+      end
+
+      def execute(sql, binds = [])
+        if binds.empty?
+          connection.query(sql)
+        else
+          connection.prepare(sql).execute(*binds)
+        end
+        nil
+      end
+
+      def insert(sql, binds, _table)
+        execute(sql, binds)
+        connection.last_id
+      end
+
+      def connection
+        connect! unless @connection
+        @connection
+      end
+    end
+  end
+end

data/lib/constable/storage/postgres_adapter.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require "constable/storage"
+
+module Constable
+  module Storage
+    # Optional blotter for teams that genuinely need one queryable store shared across
+    # many CI machines -- a cross-repo flaky-test dashboard, which is a different problem
+    # from local bookkeeping. For everything else the default SQLite adapter is faster,
+    # simpler and dependency-free.
+    #
+    # == A separate connection, always
+    #
+    # This adapter opens its *own* connection from +storage.url+ and never touches
+    # ActiveRecord, the app's connection pool, or the app's database. That is not a style
+    # preference, it is the whole reason the blotter exists as a separate store:
+    #
+    #   1. Native cases wrap each test in a transaction that is rolled back afterwards.
+    #      Writing flake history through the app's connection would enlist it in that
+    #      transaction and roll the history back along with the test's fixtures -- the
+    #      blotter would come out of every run empty.
+    #   2. :unit-tier runs skip booting the Rails/DB stack entirely. There may not *be* an
+    #      app connection to borrow.
+    #   3. Even pointed at the same server, this must be a separate database (or at least
+    #      a separate connection) so that dropping and reloading the test schema never
+    #      takes the flake history with it.
+    #
+    # The +pg+ gem is not a dependency of constable-rails; it is required lazily, right
+    # where it is needed, so nobody pays for a driver they did not ask for.
+    class PostgresAdapter < RelationalAdapter
+      def close
+        @connection&.close
+        super
+      rescue StandardError
+        super
+      end
+
+      private
+
+      def connect!
+        # Config first, driver second: a missing url is a typo in config.yml and worth
+        # saying so before we go looking for a gem.
+        url = config.storage_url
+        if url.nil? || url.to_s.empty?
+          raise Constable::ConfigurationError,
+                "storage.adapter is \"postgres\" but storage.url is not set in .constable/config.yml " \
+                "(expected something like postgres://user:pass@host/constable_metadata -- and it must " \
+                "point at a database separate from your app's, never the app's test database)"
+        end
+
+        require_driver!
+
+        # Deliberately PG::Connection.new and not ActiveRecord: this connection must be
+        # outside the app's rolled-back test transaction. See the class comment.
+        @connection = PG::Connection.new(url.to_s)
+        # "relation already exists, skipping" on every idempotent setup! would otherwise
+        # land on stderr. stdout and stderr belong to the run's results.
+        @connection.exec("SET client_min_messages TO warning")
+        @connection
+      end
+
+      def require_driver!
+        require "pg"
+      rescue LoadError => e
+        raise Constable::ConfigurationError,
+              "the pg gem is required for Constable's postgres storage adapter " \
+              "(add `gem \"pg\"` to your Gemfile and run `bundle install`, or set " \
+              "storage.adapter back to \"sqlite\" in .constable/config.yml) -- #{e.message}"
+      end
+
+      def types
+        super.merge(
+          pk: "BIGSERIAL PRIMARY KEY",
+          int: "BIGINT",
+          float: "DOUBLE PRECISION"
+        )
+      end
+
+      def execute_raw(sql)
+        connection.exec(sql)
+        nil
+      end
+
+      def query(sql, binds = [])
+        connection.exec_params(to_pg(sql), binds.map { |b| cast_bind(b) }).to_a
+      end
+
+      def execute(sql, binds = [])
+        connection.exec_params(to_pg(sql), binds.map { |b| cast_bind(b) })
+        nil
+      end
+
+      # Postgres has no "last insert id" on the connection, so the id comes back from the
+      # statement itself -- but only the tables that actually have a generated id.
+      def insert(sql, binds, table)
+        sql = to_pg(sql)
+        sql = "#{sql} RETURNING id" if AUTO_ID_TABLES.include?(table)
+        result = connection.exec_params(sql, binds.map { |b| cast_bind(b) })
+        AUTO_ID_TABLES.include?(table) ? result.first&.fetch("id", nil)&.to_i : nil
+      end
+
+      # Postgres numbers its placeholders. The SQL in RelationalAdapter is written with
+      # "?" (no literal question marks appear in it), so a positional rewrite is exact.
+      def to_pg(sql)
+        index = 0
+        sql.gsub("?") { "$#{index += 1}" }
+      end
+
+      # exec_params sends every bind as text; booleans need spelling out, everything else
+      # is fine as its default to_s. Values are still bound, never interpolated.
+      def cast_bind(value)
+        case value
+        when true then 1
+        when false then 0
+        else value
+        end
+      end
+
+      def connection
+        connect! unless @connection
+        @connection
+      end
+    end
+  end
+end

data/lib/constable/storage/sqlite_adapter.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "constable/storage"
+
+module Constable
+  module Storage
+    # The default blotter: a single self-contained file at .constable/constable.sqlite3.
+    #
+    # SQLite is the right shape for this workload and the spec says why: a handful of
+    # tables, roughly one row per test per run, a dozen-ish workers. It also keeps the
+    # promise that a :unit-tier run boots without a database server -- requiring a live
+    # Postgres just to record "did this test pass" would undo the speed it is there for.
+    #
+    # WAL mode plus a busy_timeout is belt and braces rather than necessity: only the
+    # parent process writes (workers ship results back over a pipe), but a reader that
+    # wanders in -- an editor plugin, a second terminal running `constable jail` -- should
+    # never see "database is locked" while a run is writing.
+    class SqliteAdapter < RelationalAdapter
+      # How long a statement waits on a lock before giving up. Generous, because the only
+      # thing it ever waits on is a concurrent *reader* finishing.
+      BUSY_TIMEOUT_MS = 5_000
+
+      def path = config.storage_path
+
+      # Drops the handle as well as closing it, so a later query reconnects instead of
+      # reaching for a closed database. The Runner closes before forking workers, because
+      # SQLite is explicit that a connection must not be carried across a fork.
+      def close
+        @connection.close if @connection && !@connection.closed?
+        @connection = nil
+        super
+      end
+
+      private
+
+      def connect!
+        require_driver!
+        FileUtils.mkdir_p(File.dirname(path))
+        @connection = SQLite3::Database.new(path)
+        @connection.results_as_hash = true
+        @connection.busy_timeout = BUSY_TIMEOUT_MS
+        # Readers never block the writer and the writer never blocks readers.
+        @connection.execute("PRAGMA journal_mode = WAL")
+        # WAL + NORMAL is durable across process crashes, which is the only failure that
+        # matters here; a machine losing power mid-run costs us one run's bookkeeping.
+        @connection.execute("PRAGMA synchronous = NORMAL")
+        @connection
+      end
+
+      def require_driver!
+        require "sqlite3"
+      rescue LoadError => e
+        raise Constable::ConfigurationError,
+              "the sqlite3 gem is required for Constable's default storage adapter " \
+              "(add `gem \"sqlite3\"` to your Gemfile and run `bundle install`) -- #{e.message}"
+      end
+
+      def execute_raw(sql)
+        connection.execute(sql)
+        nil
+      end
+
+      def query(sql, binds = [])
+        connection.execute(sql, binds)
+      end
+
+      def execute(sql, binds = [])
+        connection.execute(sql, binds)
+        nil
+      end
+
+      def insert(sql, binds, _table)
+        connection.execute(sql, binds)
+        connection.last_insert_row_id
+      end
+
+      def connection
+        connect! if @connection.nil? || @connection.closed?
+        @connection
+      end
+    end
+  end
+end