polyrun 1.0.0

data/lib/polyrun/database/url_builder/connection/infer.rb

@@ -0,0 +1,49 @@
+module Polyrun
+  module Database
+    module UrlBuilder
+      # Infer canonical adapter name from +polyrun.yml+ +databases:+ hash.
+      module ConnectionInfer
+        module_function
+
+        INFER_ADAPTER_FROM_NESTED = [
+          %w[postgresql postgresql],
+          %w[trilogy trilogy],
+          %w[mysql2 mysql2],
+          %w[mysql mysql2],
+          %w[sqlserver sqlserver],
+          %w[mssql sqlserver],
+          %w[sqlite3 sqlite3],
+          %w[sqlite sqlite3],
+          %w[mongodb mongodb],
+          %w[mongo mongodb]
+        ].freeze
+
+        def infer_adapter_name(dh)
+          explicit = (dh["adapter"] || dh[:adapter]).to_s.strip.downcase
+          explicit = normalize_adapter_alias(explicit)
+          return explicit unless explicit.empty?
+
+          INFER_ADAPTER_FROM_NESTED.each do |key, name|
+            return name if nested_hash?(dh, key)
+          end
+          "postgresql"
+        end
+
+        def normalize_adapter_alias(name)
+          case name
+          when "postgres", "pg" then "postgresql"
+          when "mysql" then "mysql2"
+          when "mongo" then "mongodb"
+          when "mssql" then "sqlserver"
+          when "sqlite" then "sqlite3"
+          else name
+          end
+        end
+
+        def nested_hash?(dh, key)
+          dh[key].is_a?(Hash) || dh[key.to_sym].is_a?(Hash)
+        end
+      end
+    end
+  end
+end

data/lib/polyrun/database/url_builder/connection/url_builders.rb

@@ -0,0 +1,43 @@
+require "uri"
+
+module Polyrun
+  module Database
+    module UrlBuilder
+      # String construction for +DATABASE_URL+ values.
+      module ConnectionUrlBuilders
+        module_function
+
+        def build_sqlite_url(database)
+          "sqlite3:#{database}"
+        end
+
+        def build_url_authority(scheme, host, port, user, password, database)
+          if password && !password.to_s.empty?
+            u = URI.encode_www_form_component(user.to_s)
+            p = URI.encode_www_form_component(password.to_s)
+            "#{scheme}://#{u}:#{p}@#{host}:#{port}/#{database}"
+          elsif !user.to_s.empty?
+            u = URI.encode_www_form_component(user.to_s)
+            "#{scheme}://#{u}@#{host}:#{port}/#{database}"
+          else
+            "#{scheme}://#{host}:#{port}/#{database}"
+          end
+        end
+
+        def build_mongodb_url(host, port, user, password, database)
+          if user.to_s.empty?
+            return "mongodb://#{host}:#{port}/#{database}"
+          end
+
+          u = URI.encode_www_form_component(user.to_s)
+          if password && !password.to_s.empty?
+            p = URI.encode_www_form_component(password.to_s)
+            "mongodb://#{u}:#{p}@#{host}:#{port}/#{database}"
+          else
+            "mongodb://#{u}@#{host}:#{port}/#{database}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/polyrun/database/url_builder/connection.rb

@@ -0,0 +1,191 @@
+require_relative "connection/infer"
+require_relative "connection/url_builders"
+
+module Polyrun
+  module Database
+    module UrlBuilder
+      # Adapter detection, ENV fallbacks, and URL string construction (Rails +DATABASE_URL+ conventions).
+      module Connection
+        module_function
+
+        def resolve_connection(databases_hash)
+          dh = normalize_hash(databases_hash)
+          profile = connection_profile(dh)
+          blk = merged_connection_block(dh, profile)
+          scheme = profile[:scheme]
+          host = (blk["host"] || env_first(profile[:env_host]) || profile[:default_host]).to_s
+          port = (blk["port"] || env_first(profile[:env_port]) || profile[:default_port]).to_s
+          user = (blk["username"] || blk["user"] || env_first(profile[:env_user]) || profile[:default_user]).to_s
+          password = blk["password"] || env_first(profile[:env_password])
+
+          {
+            scheme: scheme,
+            host: host,
+            port: port,
+            user: user,
+            password: password
+          }
+        end
+
+        def build_database_url(database, conn)
+          scheme = conn[:scheme].to_s
+          host = conn[:host].to_s
+          port = conn[:port].to_s
+          user = conn[:user].to_s
+          password = conn[:password]
+          db = database.to_s
+
+          case scheme
+          when "postgres"
+            ConnectionUrlBuilders.build_url_authority("postgres", host, port, user, password, db)
+          when "mysql2", "trilogy"
+            ConnectionUrlBuilders.build_url_authority(scheme, host, port, user, password, db)
+          when "sqlserver"
+            ConnectionUrlBuilders.build_url_authority("sqlserver", host, port, user, password, db)
+          when "mongodb"
+            ConnectionUrlBuilders.build_mongodb_url(host, port, user, password, db)
+          when "sqlite3"
+            ConnectionUrlBuilders.build_sqlite_url(db)
+          else
+            raise Polyrun::Error, "unsupported URL scheme: #{scheme.inspect}"
+          end
+        end
+
+        def connection_profile(dh)
+          name = ConnectionInfer.infer_adapter_name(dh)
+          case name
+          when "postgresql"
+            {
+              scheme: "postgres",
+              nested_key: "postgresql",
+              default_host: "localhost",
+              default_port: "5432",
+              default_user: "postgres",
+              env_host: %w[PGHOST],
+              env_port: %w[PGPORT],
+              env_user: %w[PGUSER],
+              env_password: %w[PGPASSWORD]
+            }
+          when "mysql2"
+            nested_mysql_key(dh)
+          when "trilogy"
+            {
+              scheme: "trilogy",
+              nested_key: "trilogy",
+              default_host: "localhost",
+              default_port: "3306",
+              default_user: "root",
+              env_host: %w[MYSQL_HOST MYSQL_ADDRESS TRILOGY_HOST],
+              env_port: %w[MYSQL_PORT MYSQL_TCP_PORT TRILOGY_PORT],
+              env_user: %w[MYSQL_USER MYSQL_USERNAME TRILOGY_USER],
+              env_password: %w[MYSQL_PASSWORD MYSQL_PWD TRILOGY_PASSWORD]
+            }
+          when "sqlserver"
+            nested =
+              if ConnectionInfer.nested_hash?(dh, "sqlserver")
+                "sqlserver"
+              else
+                "mssql"
+              end
+            {
+              scheme: "sqlserver",
+              nested_key: nested,
+              default_host: "localhost",
+              default_port: "1433",
+              default_user: "sa",
+              env_host: %w[SQLSERVER_HOST MSSQL_HOST TDS_HOST],
+              env_port: %w[SQLSERVER_PORT MSSQL_PORT TDS_PORT],
+              env_user: %w[SQLSERVER_USER MSSQL_USER SA_USER],
+              env_password: %w[SQLSERVER_PASSWORD MSSQL_PASSWORD SA_PASSWORD]
+            }
+          when "sqlite3"
+            nested =
+              if ConnectionInfer.nested_hash?(dh, "sqlite3")
+                "sqlite3"
+              else
+                "sqlite"
+              end
+            {
+              scheme: "sqlite3",
+              nested_key: nested,
+              default_host: "",
+              default_port: "",
+              default_user: "",
+              env_host: [],
+              env_port: [],
+              env_user: [],
+              env_password: []
+            }
+          when "mongodb"
+            nested_mongo_key(dh)
+          else
+            raise Polyrun::Error, "unsupported databases.adapter: #{name.inspect}"
+          end
+        end
+
+        def nested_mysql_key(dh)
+          nested =
+            if ConnectionInfer.nested_hash?(dh, "mysql2")
+              "mysql2"
+            else
+              "mysql"
+            end
+          {
+            scheme: "mysql2",
+            nested_key: nested,
+            default_host: "localhost",
+            default_port: "3306",
+            default_user: "root",
+            env_host: %w[MYSQL_HOST MYSQL_ADDRESS],
+            env_port: %w[MYSQL_PORT MYSQL_TCP_PORT],
+            env_user: %w[MYSQL_USER MYSQL_USERNAME],
+            env_password: %w[MYSQL_PASSWORD MYSQL_PWD]
+          }
+        end
+
+        def nested_mongo_key(dh)
+          nested =
+            if ConnectionInfer.nested_hash?(dh, "mongodb")
+              "mongodb"
+            else
+              "mongo"
+            end
+          {
+            scheme: "mongodb",
+            nested_key: nested,
+            default_host: "localhost",
+            default_port: "27017",
+            default_user: "",
+            env_host: %w[MONGO_HOST MONGODB_HOST],
+            env_port: %w[MONGO_PORT MONGODB_PORT],
+            env_user: %w[MONGO_USER MONGODB_USER],
+            env_password: %w[MONGO_PASSWORD MONGODB_PASSWORD]
+          }
+        end
+
+        def merged_connection_block(dh, profile)
+          nk = profile[:nested_key]
+          nested = dh[nk].is_a?(Hash) ? normalize_hash(dh[nk]) : {}
+          top = dh.slice("host", "port", "username", "user", "password").transform_keys(&:to_s)
+          nested.merge(top)
+        end
+
+        def normalize_hash(h)
+          h.is_a?(Hash) ? h.transform_keys(&:to_s) : {}
+        end
+
+        def env_first(keys)
+          Array(keys).each do |k|
+            v = ENV[k]
+            return v if present?(v)
+          end
+          nil
+        end
+
+        def present?(s)
+          !s.nil? && !s.to_s.empty?
+        end
+      end
+    end
+  end
+end

data/lib/polyrun/database/url_builder/template_prepare.rb

@@ -0,0 +1,21 @@
+module Polyrun
+  module Database
+    module UrlBuilder
+      module_function
+
+      def template_prepare_env_fill_connections!(dh, primary_template, out)
+        Array(dh["connections"] || dh[:connections]).each do |c|
+          nm = (c["name"] || c[:name]).to_s
+          key = (c["env_key"] || c[:env_key]).to_s.strip
+          key = "DATABASE_URL_#{nm.upcase.tr("-", "_")}" if key.empty? && !nm.empty?
+          next if key.empty?
+
+          tname = (c["template_db"] || c[:template_db]).to_s
+          tname = primary_template if tname.empty?
+          out[key] = url_for_database_name(dh, tname)
+        end
+        out
+      end
+    end
+  end
+end

data/lib/polyrun/database/url_builder.rb

@@ -0,0 +1,160 @@
+require "shellwords"
+require "uri"
+require_relative "url_builder/connection"
+
+module Polyrun
+  module Database
+    # Builds database URLs from +polyrun.yml+ +databases+ (spec2 §5.2) — no Liquid; use ENV fallbacks.
+    # Use +adapter:+ or nested blocks: +postgresql+, +mysql+ / +mysql2+ / +trilogy+, +sqlserver+ / +mssql+,
+    # +sqlite3+ / +sqlite+, +mongodb+ / +mongo+.
+    module UrlBuilder
+      module_function
+
+      def postgres_url_for_template(databases_hash)
+        url_for_template(databases_hash)
+      end
+
+      def postgres_url_for_database_name(databases_hash, database_name)
+        url_for_database_name(databases_hash, database_name)
+      end
+
+      def postgres_url_for_shard(databases_hash, shard_index:, connection: nil)
+        url_for_shard(databases_hash, shard_index: shard_index, connection: connection)
+      end
+
+      def url_for_template(databases_hash)
+        dh = databases_hash.is_a?(Hash) ? databases_hash : {}
+        dbname = dh["template_db"] || dh[:template_db]
+        raise Polyrun::Error, "databases.template_db is required" if dbname.nil? || dbname.to_s.empty?
+
+        url_for_database_name(dh, dbname.to_s)
+      end
+
+      def url_for_database_name(databases_hash, database_name)
+        conn = Connection.resolve_connection(databases_hash)
+        Connection.build_database_url(database_name.to_s, conn)
+      end
+
+      # ENV overrides so +bin/rails db:prepare+ runs once for multi-DB apps: each connection keeps its own
+      # +migrations_paths+ (e.g. db/cache_migrate) instead of pointing DATABASE_URL at every template in turn.
+      def template_prepare_env(databases_hash)
+        dh = databases_hash.is_a?(Hash) ? databases_hash : {}
+        pt = (dh["template_db"] || dh[:template_db]).to_s
+        raise Polyrun::Error, "template_prepare_env: set databases.template_db" if pt.empty?
+
+        out = {}
+        out["DATABASE_URL"] = url_for_database_name(dh, pt)
+        template_prepare_env_fill_connections!(dh, pt, out)
+      end
+
+      def template_prepare_env_shell_log(databases_hash)
+        template_prepare_env(databases_hash).sort.map { |k, v| "#{k}=#{Shellwords.escape(v.to_s)}" }.join(" ")
+      end
+
+      def unique_template_migrate_urls(databases_hash)
+        dh = databases_hash.is_a?(Hash) ? databases_hash : {}
+        seen = {}
+        out = []
+        pt = (dh["template_db"] || dh[:template_db]).to_s
+        unless pt.empty?
+          out << url_for_database_name(dh, pt)
+          seen[pt] = true
+        end
+        Array(dh["connections"] || dh[:connections]).each do |c|
+          t = (c["template_db"] || c[:template_db]).to_s
+          t = pt if t.empty?
+          next if t.empty?
+          next if seen[t]
+
+          out << url_for_database_name(dh, t)
+          seen[t] = true
+        end
+        out
+      end
+
+      def shard_database_name(databases_hash, shard_index:, connection: nil)
+        extract_db_name(url_for_shard(databases_hash, shard_index: shard_index, connection: connection))
+      end
+
+      def template_database_name_for(databases_hash, connection: nil)
+        dh = databases_hash.is_a?(Hash) ? databases_hash : {}
+        if connection.nil?
+          return (dh["template_db"] || dh[:template_db]).to_s
+        end
+
+        c = Array(dh["connections"] || dh[:connections]).find { |x| (x["name"] || x[:name]).to_s == connection.to_s }
+        return "" unless c
+
+        (c["template_db"] || c[:template_db] || dh["template_db"] || dh[:template_db]).to_s
+      end
+
+      def shard_database_plan(databases_hash, shard_index:)
+        dh = databases_hash.is_a?(Hash) ? databases_hash : {}
+        rows = []
+        primary_shard = shard_database_name(dh, shard_index: shard_index, connection: nil)
+        primary_tmpl = template_database_name_for(dh, connection: nil)
+        if !primary_shard.empty? && !primary_tmpl.empty?
+          rows << {new_db: primary_shard, template_db: primary_tmpl}
+        end
+
+        Array(dh["connections"] || dh[:connections]).each do |c|
+          nm = (c["name"] || c[:name]).to_s
+          next if nm.empty?
+
+          sname = shard_database_name(dh, shard_index: shard_index, connection: nm)
+          tname = template_database_name_for(dh, connection: nm)
+          rows << {new_db: sname, template_db: tname} if !sname.empty? && !tname.empty?
+        end
+        rows
+      end
+
+      def url_for_shard(databases_hash, shard_index:, connection: nil)
+        dh = databases_hash.is_a?(Hash) ? databases_hash : {}
+        conn = Connection.resolve_connection(dh)
+        pattern =
+          if connection
+            conns = dh["connections"] || dh[:connections] || []
+            c = Array(conns).find { |x| (x["name"] || x[:name]).to_s == connection.to_s }
+            (c && (c["shard_db_pattern"] || c[:shard_db_pattern])) || dh["shard_db_pattern"]
+          else
+            dh["shard_db_pattern"] || dh[:shard_db_pattern]
+          end
+        pattern ||= "app_test_%{shard}"
+
+        dbname = pattern.to_s.gsub("%{shard}", Integer(shard_index).to_s).gsub("%<shard>d", format("%d", Integer(shard_index)))
+        Connection.build_database_url(dbname, conn)
+      end
+
+      def env_exports_for_databases(databases_hash, shard_index:)
+        dh = databases_hash.is_a?(Hash) ? databases_hash : {}
+        out = {}
+        primary_url = url_for_shard(dh, shard_index: shard_index)
+        out["DATABASE_URL"] = primary_url
+        out["TEST_DB_NAME"] = extract_db_name(primary_url)
+
+        conns = dh["connections"] || dh[:connections] || []
+        Array(conns).each do |c|
+          name = (c["name"] || c[:name]).to_s
+          next if name.empty?
+
+          u = url_for_shard(dh, shard_index: shard_index, connection: name)
+          key = (c["env_key"] || c[:env_key]).to_s.strip
+          key = "DATABASE_URL_#{name.upcase.tr("-", "_")}" if key.empty?
+          out[key] = u
+        end
+        out
+      end
+
+      def extract_db_name(url)
+        s = url.to_s
+        return s.sub(/\Asqlite3:/i, "") if s.match?(/\Asqlite3:/i)
+
+        URI.parse(s).path.delete_prefix("/").split("?", 2).first
+      rescue URI::InvalidURIError
+        nil
+      end
+    end
+  end
+end
+
+require_relative "url_builder/template_prepare"

data/lib/polyrun/debug.rb

@@ -0,0 +1,81 @@
+module Polyrun
+  # Opt-in tracing: set +DEBUG=1+ or +POLYRUN_DEBUG=1+ (or +true+).
+  # Logs to stderr with wall-clock timestamps; use +.time+ for monotonic durations.
+  module Debug
+    module_function
+
+    def enabled?
+      truthy?(ENV["DEBUG"]) || truthy?(ENV["POLYRUN_DEBUG"])
+    end
+
+    def log(message)
+      return unless enabled?
+
+      Polyrun::Log.warn "[polyrun debug #{wall_clock}] #{message}"
+    end
+
+    def log_kv(pairs)
+      return unless enabled?
+
+      log(pairs.map { |k, v| "#{k}=#{v.inspect}" }.join(" "))
+    end
+
+    # Same as +log+, but tags lines from parallel RSpec workers so they are not confused with the parent +polyrun+ process (stderr interleaves arbitrarily).
+    def log_worker(message)
+      return unless enabled?
+
+      if parallel_worker_process?
+        Polyrun::Log.warn "[polyrun debug #{wall_clock}] [worker pid=#{$$} shard=#{ENV.fetch("POLYRUN_SHARD_INDEX", "?")}] #{message}"
+      else
+        Polyrun::Log.warn "[polyrun debug #{wall_clock}] #{message}"
+      end
+    end
+
+    def log_worker_kv(pairs)
+      return unless enabled?
+
+      if parallel_worker_process?
+        log_kv({role: "worker", pid: $$, shard: ENV["POLYRUN_SHARD_INDEX"]}.merge(pairs))
+      else
+        log_kv(pairs)
+      end
+    end
+
+    def parallel_worker_process?
+      ENV["POLYRUN_SHARD_TOTAL"].to_i > 1
+    end
+
+    # Yields and logs monotonic duration; re-raises after logging failures.
+    def time(label)
+      t0 = nil
+      return yield unless enabled?
+
+      t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      log("#{label} … start")
+      result = yield
+      elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0
+      elapsed_s = format("%0.3f", elapsed)
+      log("#{label} … done in #{elapsed_s}s")
+      result
+    rescue => e
+      if t0
+        elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0
+        elapsed_s = format("%0.3f", elapsed)
+        log("#{label} … failed after #{elapsed_s}s: #{e.class}: #{e.message}")
+      end
+      raise
+    end
+
+    def wall_clock
+      Time.now.getlocal.strftime("%H:%M:%S.%6N")
+    end
+
+    def truthy?(value)
+      return false if value.nil?
+
+      v = value.to_s.strip.downcase
+      %w[1 true yes on].include?(v)
+    end
+    private_class_method :truthy?
+  end
+end

data/lib/polyrun/env/ci.rb

@@ -0,0 +1,65 @@
+module Polyrun
+  module Env
+    # CI-native shard index/total (spec2 §6.4) without extra gems.
+    module Ci
+      module_function
+
+      # Returns Integer shard index or nil if not inferable from CI env.
+      def detect_shard_index
+        return Integer(ENV["POLYRUN_SHARD_INDEX"]) if present?(ENV["POLYRUN_SHARD_INDEX"])
+
+        ci = truthy?(ENV["CI"])
+        if present?(ENV["CI_NODE_INDEX"]) && ci
+          return Integer(ENV["CI_NODE_INDEX"])
+        end
+        if present?(ENV["BUILDKITE_PARALLEL_JOB"]) && ci
+          return Integer(ENV["BUILDKITE_PARALLEL_JOB"])
+        end
+        if present?(ENV["CIRCLE_NODE_INDEX"]) && ci
+          return Integer(ENV["CIRCLE_NODE_INDEX"])
+        end
+
+        nil
+      rescue ArgumentError, TypeError
+        nil
+      end
+
+      # Returns Integer shard total or nil.
+      def detect_shard_total
+        return Integer(ENV["POLYRUN_SHARD_TOTAL"]) if present?(ENV["POLYRUN_SHARD_TOTAL"])
+
+        ci = truthy?(ENV["CI"])
+        if present?(ENV["CI_NODE_TOTAL"]) && ci
+          return Integer(ENV["CI_NODE_TOTAL"])
+        end
+        if present?(ENV["BUILDKITE_PARALLEL_JOB_COUNT"]) && ci
+          return Integer(ENV["BUILDKITE_PARALLEL_JOB_COUNT"])
+        end
+        if present?(ENV["CIRCLE_NODE_TOTAL"]) && ci
+          return Integer(ENV["CIRCLE_NODE_TOTAL"])
+        end
+
+        nil
+      rescue ArgumentError, TypeError
+        nil
+      end
+
+      def polyrun_env
+        e = ENV["POLYRUN_ENV"]&.strip
+        return e if present?(e)
+
+        return "ci" if truthy?(ENV["CI"])
+
+        "local"
+      end
+
+      def present?(s)
+        !s.nil? && !s.to_s.empty?
+      end
+
+      def truthy?(s)
+        %w[1 true yes].include?(s.to_s.downcase)
+      end
+    end
+  end
+end

data/lib/polyrun/log.rb

@@ -0,0 +1,70 @@
+# rubocop:disable ThreadSafety/ClassAndModuleAttributes, ThreadSafety/ClassInstanceVariable -- process-global IO routing for CLI
+module Polyrun
+  # Swappable sinks for CLI and library output. Defaults match +Kernel#warn+ (stderr) and +puts+/+print+ (stdout).
+  #
+  # Assign an IO, +StringIO+, Ruby +Logger+, or any object responding to +puts+, +write+, or +warn+ (Logger).
+  #
+  #   Polyrun::Log.stderr = Logger.new($stderr)
+  #   Polyrun::Log.stdout = StringIO.new
+  module Log
+    class << self
+      attr_writer :stderr
+      attr_writer :stdout
+
+      def stderr
+        @stderr || $stderr
+      end
+
+      def stdout
+        @stdout || $stdout
+      end
+
+      def warn(msg = nil)
+        return if msg.nil?
+
+        emit_line(stderr, msg)
+      end
+
+      def puts(msg = "")
+        if msg.nil?
+          stdout.write("\n")
+        else
+          emit_line(stdout, msg)
+        end
+      end
+
+      def print(msg = "")
+        io = stdout
+        if io.respond_to?(:write)
+          io.write(msg.to_s)
+        elsif io.respond_to?(:print)
+          io.print(msg.to_s)
+        end
+      end
+
+      # Clears custom sinks so +stderr+ / +stdout+ resolve to the current global +$stderr+ / +$stdout+ (e.g. after tests).
+      def reset_io!
+        @stderr = nil
+        @stdout = nil
+      end
+
+      private
+
+      def emit_line(io, msg)
+        s = msg.to_s
+        if logger_like?(io)
+          io.warn(s.chomp)
+        elsif io.respond_to?(:puts)
+          io.puts(s)
+        else
+          io.write(s.end_with?("\n") ? s : "#{s}\n")
+        end
+      end
+
+      def logger_like?(io)
+        io.respond_to?(:warn) && !io.is_a?(IO)
+      end
+    end
+  end
+end
+# rubocop:enable ThreadSafety/ClassAndModuleAttributes, ThreadSafety/ClassInstanceVariable