polyrun 1.0.0

data/lib/polyrun/prepare/assets.rb

@@ -0,0 +1,57 @@
+require "digest/md5"
+require "fileutils"
+require "open3"
+
+module Polyrun
+  module Prepare
+    # Asset digest and optional Rails +assets:precompile+, stdlib only.
+    module Assets
+      module_function
+
+      # Stable digest of a list of files (sorted). Directories are expanded to all files recursively.
+      def digest_sources(*paths)
+        files = []
+        paths.flatten.compact.each do |p|
+          next unless p
+
+          path = p.to_s
+          if File.directory?(path)
+            Dir.glob(File.join(path, "**", "*"), File::FNM_DOTMATCH).each do |f|
+              files << f if File.file?(f)
+            end
+          elsif File.file?(path)
+            files << path
+          end
+        end
+        files.sort!
+        combined = files.map { |f| "#{f}:#{Digest::MD5.file(f).hexdigest}" }.join("|")
+        Digest::MD5.hexdigest(combined)
+      end
+
+      # Writes digest to +marker_path+ if missing or content differs (caller runs compile when needed).
+      def stale?(marker_path, *digest_paths)
+        return true unless File.file?(marker_path)
+
+        File.read(marker_path).strip != digest_sources(*digest_paths)
+      end
+
+      def write_marker!(marker_path, *digest_paths)
+        FileUtils.mkdir_p(File.dirname(marker_path))
+        File.write(marker_path, digest_sources(*digest_paths))
+      end
+
+      # Shells out to +bin/rails assets:precompile+ when +rails_root+ contains +bin/rails+.
+      def precompile!(rails_root:, silent: true)
+        exe = File.join(rails_root, "bin", "rails")
+        raise Polyrun::Error, "Prepare::Assets: no #{exe}" unless File.executable?(exe)
+
+        cmd = [exe, "assets:precompile"]
+        _out, err, st = Open3.capture3(*cmd, chdir: rails_root)
+        Polyrun::Log.warn err if !silent && !err.empty?
+        raise Polyrun::Error, "assets:precompile failed: #{err}" unless st.success?
+
+        true
+      end
+    end
+  end
+end

data/lib/polyrun/queue/file_store.rb

@@ -0,0 +1,199 @@
+require "fileutils"
+require "json"
+require "securerandom"
+require "time"
+module Polyrun
+  module Queue
+    # File-backed queue (spec_queue.md): +queue.json+, +pending/*.json+ chunks, +done.jsonl+, +leases.json+ (OS flock).
+    class FileStore
+      CHUNK_SIZE = 500
+
+      attr_reader :root
+
+      def initialize(root)
+        @root = File.expand_path(root)
+      end
+
+      def init!(items)
+        FileUtils.mkdir_p(@root)
+        raise Polyrun::Error, "queue already exists: #{queue_path}" if File.file?(queue_path)
+
+        items = items.map(&:to_s)
+        meta = base_meta(items.size)
+        FileUtils.mkdir_p(pending_dir)
+        write_pending_chunks!(items, meta)
+        atomic_write(queue_path, JSON.generate(meta))
+        atomic_write(ledger_path, "")
+        true
+      end
+
+      def claim!(worker_id:, batch_size:)
+        batch_size = Integer(batch_size)
+        raise Polyrun::Error, "batch_size must be >= 1" if batch_size < 1
+
+        lease_id = SecureRandom.uuid
+        batch = []
+        with_lock do
+          meta = load_meta!
+          batch = take_pending_batch!(meta, batch_size)
+          leases = read_leases
+          leases[lease_id] = {
+            "worker_id" => worker_id.to_s,
+            "paths" => batch,
+            "claimed_at" => Time.now.utc.iso8601
+          }
+          write_meta!(meta)
+          write_leases!(leases)
+          append_ledger(
+            "CLAIM" => lease_id,
+            "worker_id" => worker_id.to_s,
+            "paths" => batch,
+            "pending_remaining" => meta["pending_count"]
+          )
+        end
+        {"lease_id" => lease_id, "paths" => batch}
+      end
+
+      def ack!(lease_id:, worker_id:)
+        with_lock do
+          leases = read_leases
+          lease = leases[lease_id]
+          raise Polyrun::Error, "unknown lease: #{lease_id}" unless lease
+
+          if lease["worker_id"].to_s != worker_id.to_s
+            raise Polyrun::Error, "lease worker mismatch"
+          end
+
+          leases.delete(lease_id)
+          write_leases!(leases)
+
+          paths = lease["paths"] || []
+          meta = load_meta!
+          meta["done_count"] = Integer(meta["done_count"]) + paths.size
+          append_done_lines!(paths)
+          write_meta!(meta)
+          append_ledger("ACK" => lease_id, "worker_id" => worker_id.to_s, "paths" => paths)
+        end
+        true
+      end
+
+      def status
+        with_lock do
+          meta = load_meta!
+          {
+            "pending" => Integer(meta["pending_count"]),
+            "done" => Integer(meta["done_count"]),
+            "leases" => read_leases.keys.size
+          }
+        end
+      end
+
+      private
+
+      def queue_path
+        File.join(@root, "queue.json")
+      end
+
+      def leases_path
+        File.join(@root, "leases.json")
+      end
+
+      def ledger_path
+        File.join(@root, "ledger.jsonl")
+      end
+
+      def lock_path
+        File.join(@root, "lock")
+      end
+
+      def pending_dir
+        File.join(@root, "pending")
+      end
+
+      def done_path
+        File.join(@root, "done.jsonl")
+      end
+
+      def with_lock
+        FileUtils.mkdir_p(@root)
+        File.open(lock_path, File::CREAT | File::RDWR) do |f|
+          f.flock(File::LOCK_EX)
+          yield
+        end
+      end
+
+      def base_meta(pending_count)
+        {
+          "created_at" => Time.now.utc.iso8601,
+          "pending_count" => pending_count,
+          "done_count" => 0,
+          "chunk_size" => CHUNK_SIZE
+        }
+      end
+
+      def meta_chunk_size(meta)
+        (meta["chunk_size"] || CHUNK_SIZE).to_i
+      end
+
+      def load_meta!
+        p = queue_path
+        raise Polyrun::Error, "queue not initialized; run queue init" unless File.file?(p)
+
+        data = JSON.parse(File.read(p))
+        raise Polyrun::Error, "invalid queue.json: #{p}" unless meta_ok?(data)
+
+        data
+      end
+
+      def meta_ok?(data)
+        data.is_a?(Hash) &&
+          data.key?("pending_count") &&
+          data.key?("done_count") &&
+          data.key?("chunk_size")
+      end
+
+      def write_pending_chunks!(items, meta)
+        chunk_size = meta_chunk_size(meta)
+        FileUtils.mkdir_p(pending_dir)
+        items.each_slice(chunk_size).with_index(1) do |slice, idx|
+          atomic_write(File.join(pending_dir, format("%06d.json", idx)), JSON.generate(slice))
+        end
+      end
+
+      def write_meta!(meta)
+        atomic_write(queue_path, JSON.generate(meta))
+      end
+
+      def append_done_lines!(paths)
+        return if paths.empty?
+
+        File.open(done_path, "a") do |io|
+          paths.each { |p| io.puts(JSON.generate(p.to_s)) }
+        end
+      end
+
+      def read_leases
+        return {} unless File.file?(leases_path)
+
+        JSON.parse(File.read(leases_path))
+      end
+
+      def write_leases!(h)
+        atomic_write(leases_path, JSON.generate(h))
+      end
+
+      def append_ledger(entry)
+        line = JSON.generate(entry.merge("at" => Time.now.utc.iso8601)) + "\n"
+        File.open(ledger_path, "a") { |f| f.write(line) }
+      end
+
+      def atomic_write(path, body)
+        tmp = "#{path}.tmp.#{$$}"
+        File.write(tmp, body)
+        File.rename(tmp, path)
+      end
+    end
+  end
+end
+
+require_relative "file_store_pending"

data/lib/polyrun/queue/file_store_pending.rb

@@ -0,0 +1,48 @@
+module Polyrun
+  module Queue
+    class FileStore
+      private
+
+      def sorted_chunk_files
+        Dir.glob(File.join(pending_dir, "[0-9][0-9][0-9][0-9][0-9][0-9].json")).sort
+      end
+
+      def take_pending_batch!(meta, batch_size)
+        remaining = Integer(meta["pending_count"])
+        return [] if remaining <= 0 || batch_size <= 0
+
+        batch = []
+        files = sorted_chunk_files
+        while batch.size < batch_size
+          break if files.empty?
+
+          head = files.first
+          append_from_next_chunk!(batch, batch_size, head)
+          files.shift unless File.file?(head)
+        end
+
+        meta["pending_count"] = [remaining - batch.size, 0].max
+        if meta["pending_count"].positive? && sorted_chunk_files.empty?
+          raise Polyrun::Error,
+            "queue corrupt: pending_count=#{meta["pending_count"]} but no pending chunk files under #{pending_dir}"
+        end
+
+        batch
+      end
+
+      def append_from_next_chunk!(batch, batch_size, path)
+        chunk = JSON.parse(File.read(path))
+        raise Polyrun::Error, "corrupt queue chunk: #{path}" unless chunk.is_a?(Array)
+
+        need = batch_size - batch.size
+        taken = chunk.shift(need)
+        batch.concat(taken)
+        if chunk.empty?
+          FileUtils.rm_f(path)
+        else
+          atomic_write(path, JSON.generate(chunk))
+        end
+      end
+    end
+  end
+end

data/lib/polyrun/quick/assertions.rb

@@ -0,0 +1,32 @@
+require_relative "errors"
+
+module Polyrun
+  module Quick
+    module Assertions
+      def assert(condition, message = "assertion failed")
+        raise AssertionFailed, message unless condition
+      end
+
+      def assert_equal(expected, actual, message = nil)
+        return if expected == actual
+
+        raise AssertionFailed,
+          message || "expected #{expected.inspect}, got #{actual.inspect}"
+      end
+
+      def assert_nil(obj, message = nil)
+        return if obj.nil?
+
+        raise AssertionFailed, message || "expected nil, got #{obj.inspect}"
+      end
+
+      def assert_raises(exception_class = StandardError)
+        yield
+      rescue exception_class
+        nil
+      else
+        raise AssertionFailed, "expected #{exception_class} to be raised"
+      end
+    end
+  end
+end

data/lib/polyrun/quick/errors.rb

@@ -0,0 +1,6 @@
+module Polyrun
+  module Quick
+    class Error < Polyrun::Error; end
+    class AssertionFailed < Error; end
+  end
+end

data/lib/polyrun/quick/example_group.rb

@@ -0,0 +1,66 @@
+module Polyrun
+  module Quick
+    # One +describe+ block (possibly nested). Holds +it+ / +test+ examples and hooks.
+    class ExampleGroup
+      attr_reader :name, :parent, :children, :examples, :before_hooks, :after_hooks, :lets, :let_bang_order
+
+      def initialize(name, parent: nil)
+        @name = name.to_s
+        @parent = parent
+        @children = []
+        @examples = []
+        @before_hooks = []
+        @after_hooks = []
+        @lets = {}
+        @let_bang_order = []
+      end
+
+      def full_name
+        return @name if parent.nil?
+
+        "#{parent.full_name} #{@name}".strip
+      end
+
+      def describe(name, &block)
+        child = ExampleGroup.new(name, parent: self)
+        @children << child
+        child.instance_eval(&block) if block
+        child
+      end
+
+      def it(description, &block)
+        @examples << [description.to_s, block]
+      end
+
+      alias_method :test, :it
+
+      def before(&block)
+        @before_hooks << block
+      end
+
+      def after(&block)
+        @after_hooks << block
+      end
+
+      def let(name, &block)
+        @lets[name.to_sym] = block
+      end
+
+      def let!(name, &block)
+        sym = name.to_sym
+        @lets[sym] = block
+        @let_bang_order << sym
+      end
+
+      def each_example_with_ancestors(ancestors = [], &visitor)
+        chain = ancestors + [self]
+        @examples.each do |desc, block|
+          visitor.call(chain, desc, block)
+        end
+        @children.each do |child|
+          child.each_example_with_ancestors(chain, &visitor)
+        end
+      end
+    end
+  end
+end

data/lib/polyrun/quick/example_runner.rb

@@ -0,0 +1,93 @@
+require_relative "assertions"
+require_relative "errors"
+require_relative "matchers"
+
+module Polyrun
+  module Quick
+    # Per-example execution: merged lets, hooks, assertions, optional Capybara::DSL.
+    class ExampleRunner
+      include Assertions
+      include Matchers
+
+      def initialize(reporter)
+        @reporter = reporter
+        @_let_cache = {}
+      end
+
+      def run(group_name:, description:, ancestor_chain:, block:)
+        @_let_cache = {}
+        merge_lets_from_chain(ancestor_chain)
+        define_let_methods!
+        run_let_bangs_from_chain
+        extend_capybara_if_enabled!
+        begin
+          run_before_hooks_from_chain(ancestor_chain)
+          instance_eval(&block)
+          @reporter.pass(group_name, description)
+        rescue AssertionFailed => e
+          @reporter.fail(group_name, description, e)
+        rescue => e
+          @reporter.error(group_name, description, e)
+        ensure
+          run_after_hooks_from_chain(ancestor_chain)
+          reset_capybara_if_enabled!
+          @_let_cache = {}
+        end
+      end
+
+      private
+
+      def merge_lets_from_chain(ancestor_chain)
+        @merged_lets = {}
+        ancestor_chain.each do |g|
+          @merged_lets.merge!(g.lets)
+        end
+        @let_bang_order = []
+        ancestor_chain.each do |g|
+          @let_bang_order.concat(g.let_bang_order)
+        end
+      end
+
+      def define_let_methods!
+        @merged_lets.each do |sym, proc|
+          define_singleton_method(sym) do
+            @_let_cache[sym] ||= instance_eval(&proc) # rubocop:disable ThreadSafety/ClassInstanceVariable -- per-example runner memo
+          end
+        end
+      end
+
+      def run_let_bangs_from_chain
+        @let_bang_order.each { |sym| public_send(sym) }
+      end
+
+      def run_before_hooks_from_chain(ancestor_chain)
+        ancestor_chain.each do |g|
+          g.before_hooks.each { |h| instance_eval(&h) }
+        end
+      end
+
+      def run_after_hooks_from_chain(ancestor_chain)
+        ancestor_chain.reverse_each do |g|
+          g.after_hooks.reverse_each { |h| instance_eval(&h) }
+        end
+      end
+
+      def extend_capybara_if_enabled!
+        return unless Quick.capybara?
+        return unless defined?(::Capybara)
+        return unless defined?(::Capybara::DSL)
+
+        extend ::Capybara::DSL
+      end
+
+      def reset_capybara_if_enabled!
+        return unless Quick.capybara?
+        return unless defined?(::Capybara)
+
+        ::Capybara.reset_sessions!
+      rescue
+        # Driver/session may be absent in non-Capybara runs
+      end
+    end
+  end
+end

data/lib/polyrun/quick/matchers.rb

@@ -0,0 +1,156 @@
+require_relative "errors"
+
+module Polyrun
+  module Quick
+    # Minimal +expect(x).to …+ chain (RSpec-ish) without RSpec.
+    class Expectation
+      def initialize(actual)
+        @actual = actual
+      end
+
+      def to(matcher)
+        return if matcher.matches?(@actual)
+
+        raise AssertionFailed, matcher.failure_message(@actual)
+      end
+
+      def not_to(matcher)
+        return if matcher.does_not_match?(@actual)
+
+        raise AssertionFailed, matcher.failure_message_when_negated(@actual)
+      end
+    end
+
+    module Matchers
+      def expect(actual)
+        Expectation.new(actual)
+      end
+
+      def eq(expected)
+        EqMatcher.new(expected)
+      end
+
+      def be_truthy
+        TruthyMatcher.new
+      end
+
+      def be_falsey
+        FalseyMatcher.new
+      end
+
+      def include(*expected)
+        IncludeMatcher.new(expected)
+      end
+
+      def match(pattern)
+        RegexMatcher.new(pattern)
+      end
+    end
+
+    class EqMatcher
+      def initialize(expected)
+        @expected = expected
+      end
+
+      def matches?(actual)
+        @expected == actual
+      end
+
+      def does_not_match?(actual)
+        !matches?(actual)
+      end
+
+      def failure_message(actual)
+        "expected #{@expected.inspect}, got #{actual.inspect}"
+      end
+
+      def failure_message_when_negated(actual)
+        "expected #{actual.inspect} not to eq #{@expected.inspect}"
+      end
+    end
+
+    class TruthyMatcher
+      def matches?(actual)
+        !!actual
+      end
+
+      def does_not_match?(actual)
+        !matches?(actual)
+      end
+
+      def failure_message(actual)
+        "expected truthy, got #{actual.inspect}"
+      end
+
+      def failure_message_when_negated(actual)
+        "expected falsey, got #{actual.inspect}"
+      end
+    end
+
+    class FalseyMatcher
+      def matches?(actual)
+        !actual
+      end
+
+      def does_not_match?(actual)
+        !matches?(actual)
+      end
+
+      def failure_message(actual)
+        "expected falsey, got #{actual.inspect}"
+      end
+
+      def failure_message_when_negated(actual)
+        "expected truthy, got #{actual.inspect}"
+      end
+    end
+
+    class IncludeMatcher
+      def initialize(expected_parts)
+        @expected_parts = expected_parts
+      end
+
+      def matches?(actual)
+        return false unless actual.respond_to?(:include?)
+
+        @expected_parts.all? { |part| actual.include?(part) }
+      end
+
+      def does_not_match?(actual)
+        !matches?(actual)
+      end
+
+      def failure_message(actual)
+        "expected #{actual.inspect} to include #{@expected_parts.map(&:inspect).join(", ")}"
+      end
+
+      def failure_message_when_negated(actual)
+        "expected #{actual.inspect} not to include #{@expected_parts.map(&:inspect).join(", ")}"
+      end
+    end
+
+    class RegexMatcher
+      def initialize(pattern)
+        @pattern = pattern
+      end
+
+      def matches?(actual)
+        return false unless actual.respond_to?(:to_s)
+
+        @pattern === actual.to_s
+      end
+
+      def does_not_match?(actual)
+        !matches?(actual)
+      end
+
+      def failure_message(actual)
+        "expected #{actual.inspect} to match #{@pattern.inspect}"
+      end
+
+      def failure_message_when_negated(actual)
+        "expected #{actual.inspect} not to match #{@pattern.inspect}"
+      end
+    end
+  end
+end

data/lib/polyrun/quick/reporter.rb

@@ -0,0 +1,42 @@
+module Polyrun
+  module Quick
+    class Reporter
+      def initialize(out, err, verbose)
+        @out = out
+        @err = err
+        @verbose = verbose
+        @passed = 0
+        @failed = 0
+        @errors = 0
+      end
+
+      def pass(group, description)
+        @passed += 1
+        return unless @verbose
+
+        @out.puts "  ok  #{group} #{description}"
+      end
+
+      def fail(group, description, exc)
+        @failed += 1
+        @err.puts "  FAIL  #{group} #{description}"
+        @err.puts "         #{exc.message}"
+      end
+
+      def error(group, description, exc)
+        @errors += 1
+        @err.puts "  ERROR #{group} #{description}"
+        @err.puts "         #{exc.class}: #{exc.message}"
+        loc = exc.backtrace&.first
+        @err.puts "         #{loc}" if loc
+      end
+
+      def summary
+        total = @passed + @failed + @errors
+        @out.puts
+        @out.puts "Polyrun::Quick: #{@passed} passed, #{@failed} failed, #{@errors} errors (#{total} examples)"
+        (@failed + @errors).positive? ? 1 : 0
+      end
+    end
+  end
+end