gemstack 0.2.5 → 0.3.0

data/lib/gemstack/contract/typescript.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module GemStack
+  module Contract
+    # Emits TypeScript from the contract IR:
+    #   types.ts          one `export type` per serializer / input schema
+    #   <resource>.ts     a typed client object per controller
+    #   index.ts          re-exports everything
+    #
+    # Shapes are type aliases (not interfaces) so they are assignable to the
+    # client's Query record type.
+    class TypeScript
+      def initialize(contract, client_import: "@/lib/gemstack/client")
+        @contract = contract
+        @client_import = client_import
+      end
+
+      def files
+        files = { "types.ts" => types_file }
+        @contract[:resources].each { |resource| files["#{file_base(resource)}.ts"] = resource_file(resource) }
+        files["index.ts"] = index_file
+        files
+      end
+
+      PAGE_TYPES = <<~TS
+        /** The pagination envelope returned by `paginate` in controllers. */
+        export type PaginationMeta = {
+          page: number;
+          per_page: number;
+          total: number;
+          total_pages: number;
+        };
+
+        export type Paginated<T> = {
+          data: T[];
+          meta: PaginationMeta;
+        };
+
+        export type PaginationQuery = {
+          page?: number;
+          per_page?: number;
+        };
+      TS
+
+      private
+
+      def header = "// #{HEADER}\n"
+
+      def types_file
+        body = @contract[:types].map do |name, type|
+          "export type #{name} = #{object_type(type[:fields], 0)};\n"
+        end
+        body.unshift(PAGE_TYPES) if paginated?
+        # No types yet (a new app): still a module, or `export type * from "./types"` fails to compile.
+        body << "export {};\n" if body.empty?
+        "#{header}\n#{body.join("\n")}"
+      end
+
+      def paginated? = @contract[:resources].any? { |r| r[:endpoints].any? { |e| e[:paginated] } }
+
+      def object_type(fields, depth)
+        return "Record<string, never>" if fields.empty?
+
+        pad = "  " * (depth + 1)
+        lines = fields.map do |field|
+          type = ts_type(field[:type], depth + 1)
+          type = "#{type} | null" if field[:nullable]
+          "#{pad}#{property(field[:name])}#{"?" if field[:optional]}: #{type};"
+        end
+        "{\n#{lines.join("\n")}\n#{"  " * depth}}"
+      end
+
+      def ts_type(ref, depth = 0)
+        if ref[:scalar] then Types.fetch(ref[:scalar]).ts
+        elsif ref[:ref] then ref[:ref]
+        elsif ref[:array]
+          inner = ts_type(ref[:array], depth)
+          inner.match?(/\A[\w.]+\z/) ? "#{inner}[]" : "Array<#{inner}>"
+        elsif ref[:page] then "Paginated<#{ts_type(ref[:page], depth)}>"
+        elsif ref[:object] then object_type(ref[:object], depth)
+        else "unknown"
+        end
+      end
+
+      def property(name) = name.match?(/\A[A-Za-z_$][\w$]*\z/) ? name : name.inspect
+
+      def resource_file(resource)
+        refs = []
+        methods = resource[:endpoints].map { |endpoint| client_method(endpoint, refs) }
+        imports = refs.uniq.sort
+        lines = [header]
+        lines << %(import { api, type RequestOptions } from "#{@client_import}";)
+        lines << %(import type { #{imports.join(", ")} } from "./types";) unless imports.empty?
+        lines << ""
+        lines << "const segment = (value: string | number) => encodeURIComponent(String(value));"
+        lines << ""
+        lines << "export const #{export_name(resource)} = {"
+        lines.concat(methods)
+        lines << "};"
+        "#{lines.join("\n")}\n"
+      end
+
+      def client_method(endpoint, refs)
+        args = endpoint[:params].map { |param| "#{camel(param)}: string | number" }
+        collect_refs(endpoint[:body], refs)
+        collect_refs(endpoint[:query], refs)
+        collect_refs(endpoint[:response], refs)
+        args << "data: #{ts_type(endpoint[:body])}" if endpoint[:body]
+        args << query_arg(endpoint) if endpoint[:query] || endpoint[:paginated]
+        refs << "PaginationQuery" if endpoint[:paginated]
+        args << "options?: RequestOptions"
+        response = endpoint[:response] ? ts_type(endpoint[:response]) : "void"
+        call = "api.#{client_verb(endpoint[:verb])}<#{response}>(#{call_args(endpoint)})"
+        "  /** #{endpoint[:verb]} #{@contract[:api_path]}#{endpoint[:path]} */\n  " \
+          "#{endpoint[:name]}: (#{args.join(", ")}) => #{call},"
+      end
+
+      # Paginated lists take an optional { page, per_page } query, combined
+      # with the action's own query schema when there is one.
+      def query_arg(endpoint)
+        return "query: #{ts_type(endpoint[:query])}" unless endpoint[:paginated]
+        return "query?: PaginationQuery" unless endpoint[:query]
+
+        "query: #{ts_type(endpoint[:query])} & PaginationQuery"
+      end
+
+      def call_args(endpoint)
+        path = endpoint[:path].gsub(/[:*](\w+)/) { "${segment(#{camel(::Regexp.last_match(1))})}" }
+        path = path.include?("${") ? "`#{path}`" : path.inspect
+        options = endpoint[:query] || endpoint[:paginated] ? "{ ...options, query }" : "options"
+        case client_verb(endpoint[:verb])
+        when "get", "delete" then "#{path}, #{options}"
+        else "#{path}, #{endpoint[:body] ? "data" : "undefined"}, #{options}"
+        end
+      end
+
+      def client_verb(verb) = { "HEAD" => "get", "OPTIONS" => "get" }.fetch(verb, verb.downcase)
+
+      def collect_refs(ref, refs)
+        return unless ref
+
+        refs << ref[:ref] if ref[:ref]
+        refs << "Paginated" if ref[:page]
+        collect_refs(ref[:array], refs) if ref[:array]
+        collect_refs(ref[:page], refs) if ref[:page]
+      end
+
+      def index_file
+        exports = @contract[:resources].map { |r| %(export { #{export_name(r)} } from "./#{file_base(r)}";) }
+        "#{header}\nexport type * from \"./types\";\n#{exports.join("\n")}\n"
+      end
+
+      def file_base(resource) = resource[:name].tr("/", "_")
+      def export_name(resource) = camel(resource[:name].tr("/", "_"))
+
+      def camel(name)
+        camel = Inflector.camelize(name)
+        camel[0].downcase + camel[1..]
+      end
+    end
+  end
+end

data/lib/gemstack/contract.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+require "gemstack/core"
+require "gemstack/schema"
+require "gemstack/http"
+
+module GemStack
+  # The API contract: derived from the backend (routes + controller `accepts`
+  # schemas + serializers) and emitted as TypeScript types, a typed client
+  # per resource, and OpenAPI 3.1 (ARCHITECTURE §8).
+  #
+  #   contract = GemStack::Contract.build(GemStack.boot!)
+  #   GemStack::Contract.write(contract, root: GemStack.root)
+  module Contract
+    class Config < Settings
+      setting :output_dir, default: "frontend/lib/api/generated"
+      setting :openapi_path, default: "openapi.json"
+      # Import path of the client runtime from generated files.
+      setting :client_import, default: "@/lib/gemstack/client"
+      # Interactive API docs at <api_path>/docs, built from the live routes (development only by default).
+      setting :docs, default: -> { GemStack.env.development? }
+    end
+
+    HEADER = "Generated by GemStack from the backend — do not edit. Run `gemstack contract` to regenerate."
+
+    class << self
+      def config = GemStack.config.contract
+
+      # Builds the contract IR from a booted application (eager-loads code).
+      def build(app)
+        app.eager_load!
+        Builder.new(routes: app.routes, api_path: app.config.http.api_path).build
+      end
+
+      # Writes TypeScript and OpenAPI files, touching only files whose content
+      # changed (so Next.js doesn't hot-reload needlessly) and removing
+      # generated files for resources that no longer exist. Returns
+      # { written: [...], removed: [...], unchanged: [...] }. dry_run: true
+      # reports what would change without touching anything (`gemstack doctor`).
+      def write(contract, root:, output_dir: config.output_dir, openapi_path: config.openapi_path, typescript: true,
+                dry_run: false)
+        dir = File.expand_path(output_dir, root)
+        files = typescript ? TypeScript.new(contract, client_import: config.client_import).files : {}
+        report = { written: [], removed: [], unchanged: [] }
+        files.each { |name, content| write_file(File.join(dir, name), content, report, dry_run: dry_run) }
+        stale = typescript ? Dir.glob(File.join(dir, "*.ts")) : []
+        stale = stale.reject { |path| files.key?(File.basename(path)) }
+        stale.each do |path|
+          next unless File.read(path).include?(HEADER)
+
+          File.delete(path) unless dry_run
+          report[:removed] << path
+        end
+        if openapi_path
+          write_file(File.expand_path(openapi_path, root), "#{JSON.pretty_generate(OpenAPI.new(contract).document)}\n",
+                     report, dry_run: dry_run)
+        end
+        report
+      end
+
+      private
+
+      def write_file(path, content, report, dry_run: false)
+        if File.exist?(path) && File.read(path) == content
+          report[:unchanged] << path
+          return
+        end
+        return report[:written] << path if dry_run
+
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, content)
+        report[:written] << path
+      end
+    end
+  end
+
+  Config.namespace(:contract, Contract::Config)
+end
+
+require_relative "contract/builder"
+require_relative "contract/typescript"
+require_relative "contract/openapi"
+require_relative "contract/docs"
+
+GemStack::Plugins.register(:contract_docs) do |app|
+  next unless app.respond_to?(:routes) && app.config.contract.docs
+
+  stack = app.config.http.middleware
+  stack.insert_before(GemStack::HTTP::Middleware::HealthCheck, GemStack::Contract::Docs, app) unless
+    stack.include?(GemStack::Contract::Docs)
+end

data/lib/gemstack/core.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "securerandom"
+require "fileutils"
+require_relative "version"
+require_relative "settings"
+require_relative "environment"
+require_relative "dotenv"
+require_relative "errors"
+require_relative "error_mapping"
+require_relative "logger"
+require_relative "inflector"
+require_relative "plugins"
+
+module GemStack
+  # Root configuration. Modules add namespaces to it:
+  #   GemStack::Config.namespace(:http, GemStack::HTTP::Config)
+  class Config < Settings
+    setting :name, default: -> { File.basename(root) }
+    setting :root, default: -> { Dir.pwd }
+
+    # .env files loaded at boot, earlier files win. Real ENV always wins.
+    setting :env_files, default: lambda {
+      env = GemStack.env
+      env.local? ? [".env.#{env}.local", ".env.local", ".env.#{env}", ".env"] : []
+    }
+
+    # Root secret for signatures (storage URLs, derived keys). Production must
+    # set SECRET_KEY_BASE; development/test generate one in tmp/ (git-ignored).
+    setting :secret_key_base, default: lambda {
+      ENV.fetch("SECRET_KEY_BASE", nil) || (GemStack.env.local? ? GemStack.send(:local_secret) : nil)
+    }
+
+    # Keys (substring, case-insensitive) masked in logs and error output.
+    setting :filter_parameters, default: %w[password passwd secret token api_key apikey authorization cookie
+                                            credit_card card_number cvv ssn private_key]
+
+    namespace :logger do
+      setting :level, default: -> { ENV.fetch("GEMSTACK_LOG_LEVEL") { GemStack.env.production? ? "info" : "debug" } }
+      setting :format, default: -> { GemStack.env.local? ? :pretty : :json }
+      # Test logs are discarded unless GEMSTACK_LOG_LEVEL is set explicitly.
+      setting :output, default: -> { GemStack.env.test? && !ENV["GEMSTACK_LOG_LEVEL"] ? nil : $stdout }
+      # nil = colour when output is a terminal. `gemstack dev` sets
+      # GEMSTACK_LOG_COLOR=1 because child output goes through a pipe.
+      setting :color, default: -> { ENV["GEMSTACK_LOG_COLOR"]&.then { |v| v == "1" } }
+    end
+  end
+
+  class << self
+    def config
+      @config ||= Config.new
+    end
+
+    def configure
+      yield config
+      config
+    end
+
+    def env
+      @env ||= Environment.detect
+    end
+
+    def env=(name)
+      @env = name.is_a?(Environment) ? name : Environment.new(name)
+    end
+
+    def root
+      Pathname.new(config.root)
+    end
+
+    # First call in config/app.rb: sets the application root and loads .env
+    # files (development/test) before anything reads configuration or ENV.
+    def setup(root:)
+      config.root = root.to_s
+      load_env_files!
+      self
+    end
+
+    # Idempotent; real ENV variables are never overwritten.
+    def load_env_files!
+      files = config.env_files.map { |file| File.expand_path(file, config.root) }
+      return if @loaded_env_files == files
+
+      Dotenv.load(files)
+      @loaded_env_files = files
+    end
+
+    def logger
+      @logger ||= begin
+        settings = config.logger
+        Logger.new(settings.output, level: settings.level, format: settings.format,
+                                    filter: config.filter_parameters, color: settings.color)
+      end
+    end
+
+    attr_writer :logger
+
+    # A 32-byte key for one purpose, derived from secret_key_base, so a key
+    # leaked for one use (e.g. storage URLs) can't sign anything else.
+    def key_for(purpose)
+      secret = config.secret_key_base
+      if secret.to_s.empty?
+        raise ConfigurationError,
+              "SECRET_KEY_BASE is not set (generate one with: openssl rand -hex 64)"
+      end
+
+      OpenSSL::HMAC.digest("SHA256", secret, "gemstack:#{purpose}")
+    end
+
+    # Forget all process-level state. Intended for tests.
+    def reset!
+      @config = nil
+      @env = nil
+      @logger = nil
+      @loaded_env_files = nil
+    end
+
+    private
+
+    def local_secret
+      path = File.join(config.root, "tmp", "#{env}_secret")
+      return File.read(path).strip if File.file?(path)
+
+      FileUtils.mkdir_p(File.dirname(path))
+      SecureRandom.hex(64).tap { |secret| File.write(path, secret, perm: 0o600) }
+    end
+  end
+end

data/lib/gemstack/db/configuration.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require "erb"
+require "uri"
+require "yaml"
+
+module GemStack
+  module DB
+    # Where the connection settings come from, first match wins:
+    #
+    #   1. config.db.url, set in config/app.rb or config/environments/*.rb
+    #   2. DATABASE_URL (TEST_DATABASE_URL in the test environment)
+    #   3. config/database.yml — the section for the current environment
+    #   4. PostgreSQL on this machine, database <app>_<env> (apps without database.yml)
+    #
+    # config/database.yml works like Rails' (ERB allowed):
+    #
+    #   default: &default
+    #     adapter: postgresql          # postgresql, mysql2, trilogy or sqlite3
+    #     pool: <%= ENV.fetch("GEMSTACK_MAX_THREADS", 5) %>
+    #   development:
+    #     <<: *default
+    #     database: shop_development
+    #   test:
+    #     <<: *default
+    #     database: shop_test
+    #   production:
+    #     <<: *default
+    #     url: <%= ENV["DATABASE_URL"] %>
+    #
+    # The result is a Hash for Sequel.connect: { adapter: "postgres", database:, host:, … }.
+    module Configuration
+      # Rails-style names (and URL schemes) → Sequel adapters.
+      ADAPTERS = {
+        "postgresql" => "postgres", "postgres" => "postgres", "postgis" => "postgres",
+        "mysql2" => "mysql2", "mysql" => "mysql2", "trilogy" => "trilogy",
+        "sqlite3" => "sqlite", "sqlite" => "sqlite"
+      }.freeze
+      # The gem each adapter needs in the application's Gemfile.
+      DRIVER_GEMS = { "postgres" => "pg", "mysql2" => "mysql2", "trilogy" => "trilogy", "sqlite" => "sqlite3" }.freeze
+      # database.yml keys with another name in Sequel.
+      RENAMED = { "username" => :user, "pool" => :max_connections }.freeze
+      # database.yml keys Rails uses that mean nothing to Sequel.
+      IGNORED = %w[schema_search_path migrations_paths reaping_frequency idle_timeout checkout_timeout].freeze
+
+      module_function
+
+      def resolve(config: DB.config, env: GemStack.env, root: GemStack.config.root)
+        return from_url(config.url, root: root).merge(source: "config.db.url") if config.url
+
+        variable = env.test? ? "TEST_DATABASE_URL" : "DATABASE_URL"
+        url = ENV.fetch(variable, "").strip
+        yaml = yaml_settings(root, env)
+        return from_url(url, root: root).merge(pool_from(yaml)).merge(source: variable) unless url.empty?
+        return yaml.merge(source: "config/database.yml (#{env})") if yaml
+
+        name = "#{GemStack.config.name.to_s.tr("-", "_")}_#{env}"
+        { adapter: "postgres", database: name, source: "default (no config/database.yml)" }
+      end
+
+      # The section of config/database.yml for this environment, normalized; nil without the file.
+      def yaml_settings(root, env)
+        path = File.join(root.to_s, "config", "database.yml")
+        return nil unless File.file?(path)
+
+        data = YAML.safe_load(ERB.new(File.read(path)).result, aliases: true, filename: path) || {}
+        section = data[env.to_s] or raise ConfigurationError, "config/database.yml has no #{env} section"
+        raise ConfigurationError, "config/database.yml: #{env} must be a mapping" unless section.is_a?(Hash)
+
+        from_hash(section, root: root)
+      rescue Psych::Exception => e
+        raise ConfigurationError, "config/database.yml: #{e.message}"
+      end
+
+      def from_hash(section, root:)
+        url = section["url"].to_s.strip
+        base = url.empty? ? {} : from_url(url, root: root)
+        settings = section.each_with_object({}) do |(key, value), out|
+          next if key == "url" || IGNORED.include?(key) || value.nil?
+
+          out[RENAMED.fetch(key, key.to_sym)] = value
+        end
+        settings = base.merge(settings) { |_, from_url, from_keys| from_keys || from_url }
+        settings[:adapter] = adapter!(settings[:adapter]) if settings[:adapter]
+        raise ConfigurationError, "config/database.yml: set adapter (or url)" unless settings[:adapter]
+
+        settings[:max_connections] = Integer(settings[:max_connections]) if settings[:max_connections]
+        settings[:port] = Integer(settings[:port]) if settings[:port]
+        sqlite_path(settings, root)
+      end
+
+      # postgres://user:pass@host:5432/name?sslmode=require, mysql2://…, trilogy://…,
+      # sqlite3:db/development.sqlite3 (relative to the app), sqlite3:///abs/path.db, sqlite3::memory:
+      def from_url(url, root:)
+        scheme = url[/\A([a-z0-9+.-]+):/i, 1].to_s.downcase
+        adapter = adapter!(scheme)
+        if adapter == "sqlite"
+          path = url.sub(/\A[^:]+:/, "").sub(%r{\A//}, "").sub(/\?.*\z/, "")
+          return sqlite_path({ adapter: adapter, database: path }, root)
+        end
+
+        uri = URI.parse(url)
+        settings = { adapter: adapter, host: uri.host, port: uri.port,
+                     database: decode(uri.path.to_s.delete_prefix("/")), user: decode(uri.user),
+                     password: decode(uri.password) }
+        URI.decode_www_form(uri.query.to_s).each { |key, value| settings[key.to_sym] = value }
+        settings.reject { |_, value| value.nil? || value == "" }
+      rescue URI::InvalidURIError => e
+        raise ConfigurationError, "invalid database URL: #{e.message}"
+      end
+
+      def adapter!(name)
+        ADAPTERS.fetch(name.to_s.downcase) do
+          raise ConfigurationError, "unsupported database adapter #{name.inspect} " \
+                                    "(use postgresql, mysql2, trilogy or sqlite3)"
+        end
+      end
+
+      def pool_from(yaml) = yaml && yaml[:max_connections] ? { max_connections: yaml[:max_connections] } : {}
+
+      def sqlite_path(settings, root)
+        return settings unless settings[:adapter] == "sqlite"
+
+        database = settings[:database].to_s
+        if database.empty?
+          raise ConfigurationError,
+                "sqlite3 needs a database file (e.g. database: db/development.sqlite3)"
+        end
+
+        settings[:database] = File.expand_path(database, root.to_s) unless database == ":memory:"
+        settings
+      end
+
+      def decode(value) = value && URI.decode_www_form_component(value)
+
+      # For logs and `gemstack doctor`: no passwords.
+      def describe(settings)
+        if settings[:adapter] == "sqlite"
+          return "sqlite3 #{settings[:database].to_s.delete_prefix("#{GemStack.config.root}/")}"
+        end
+
+        host = settings[:host] || "localhost"
+        user = settings[:user] ? "#{settings[:user]}@" : ""
+        "#{settings[:adapter]}://#{user}#{host}#{":#{settings[:port]}" if settings[:port]}/#{settings[:database]}"
+      end
+    end
+  end
+end

data/lib/gemstack/db/errors.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module GemStack
+  module DB
+    # Gives Sequel errors their HTTP meaning via GemStack::ErrorMapping (no
+    # dependency on the HTTP layer), for PostgreSQL, MySQL and SQLite:
+    #
+    #   record not found           → 404 not_found
+    #   model validation failed    → 422 validation_failed + field errors
+    #   unique / not-null / FK     → 422 with the offending column when the database names it
+    #   row still referenced (FK)  → 409 conflict
+    #   database unreachable       → 503 service_unavailable
+    module Errors
+      KEY_DETAIL = /Key \(([^)]+)\)=/ # PostgreSQL
+      MYSQL_KEY = /Duplicate entry .* for key '(?:[^.']+\.)?([^']+)'/   # MySQL 8 names table.index
+      SQLITE_COLUMNS = /constraint failed: ((?:[\w.]+(?:, )?)+)/i       # UNIQUE / NOT NULL
+      FK_COLUMN = /FOREIGN KEY \(`?([^`)]+)`?\)/                        # MySQL
+
+      module_function
+
+      def install!
+        # Registered first: the specific classes below take precedence.
+        ErrorMapping.register(Sequel::DatabaseError) { |error| mysql_missing_value(error) }
+        install_record_errors!
+        install_constraint_errors!
+        ErrorMapping.register(Sequel::DatabaseConnectionError) { ServiceUnavailable.new("Database unavailable") }
+        ErrorMapping.register(Sequel::PoolTimeout) { ServiceUnavailable.new("Database busy, try again") }
+      end
+
+      def install_record_errors!
+        ErrorMapping.register(Sequel::NoMatchingRow) do |error|
+          model = error.respond_to?(:dataset) && error.dataset.respond_to?(:model) ? error.dataset.model : nil
+          RecordNotFound.new(model&.name ? "#{model.name} not found" : "Record not found")
+        end
+        ErrorMapping.register(Sequel::ValidationFailed) do |error|
+          ValidationError.new(errors: stringify(error.errors))
+        end
+        ErrorMapping.register(Sequel::InvalidValue) do |error|
+          ValidationError.new(error.message.sub(/\A.*?: /, "Invalid value: "), code: "invalid_value")
+        end
+        ErrorMapping.register(Sequel::MassAssignmentRestriction) do |error|
+          BadRequest.new(error.message, code: "unknown_attribute")
+        end
+      end
+
+      def install_constraint_errors!
+        ErrorMapping.register(Sequel::UniqueConstraintViolation) do |error|
+          field_error(columns(error), "is already taken") || Conflict.new("Record already exists")
+        end
+        ErrorMapping.register(Sequel::NotNullConstraintViolation) do |error|
+          field_error([column(error)].compact, "is required") || ValidationError.new("A required value is missing")
+        end
+        ErrorMapping.register(Sequel::ForeignKeyConstraintViolation) do |error|
+          if referenced_missing?(error)
+            field_error(columns(error), "does not exist") || ValidationError.new("A referenced record does not exist")
+          else
+            Conflict.new("Record is still referenced by other records", code: "still_referenced")
+          end
+        end
+        ErrorMapping.register(Sequel::CheckConstraintViolation) do
+          ValidationError.new("A value violates a database constraint", code: "constraint_violation")
+        end
+      end
+
+      # MySQL (strict mode) reports an omitted NOT NULL column without a
+      # default as a plain error: "Field 'name' doesn't have a default value".
+      def mysql_missing_value(error)
+        name = error.message[/Field '([^']+)' doesn't have a default value/, 1]
+        name && ValidationError.new(errors: { name => ["is required"] })
+      end
+
+      def stringify(errors) = errors.to_h { |key, messages| [Array(key).join(","), Array(messages)] }
+
+      def field_error(names, message)
+        return nil if names.empty?
+
+        ValidationError.new(errors: names.to_h { |name| [name, [message]] })
+      end
+
+      def pg_error(error) = error.respond_to?(:wrapped_exception) ? error.wrapped_exception : nil
+
+      # PostgreSQL: "is not present in table"; MySQL: "Cannot add or update a child row".
+      # SQLite doesn't say which side failed, so it is reported as a conflict.
+      def referenced_missing?(error)
+        message = error.message
+        message.include?("is not present") || message.include?("Cannot add or update a child row")
+      end
+
+      # The columns named by a unique or foreign-key violation, when the database says.
+      def columns(error)
+        message = error.message
+        if (detail = pg_detail(error) || message[KEY_DETAIL]) && (match = KEY_DETAIL.match(detail))
+          match[1].split(",").map(&:strip).map { |c| c.delete('"') }
+        elsif (match = SQLITE_COLUMNS.match(message))
+          match[1].split(", ").map { |name| name.split(".").last }
+        elsif (match = FK_COLUMN.match(message))
+          [match[1]]
+        elsif (match = MYSQL_KEY.match(message))
+          index_column(match[1])
+        else
+          []
+        end
+      rescue StandardError
+        []
+      end
+
+      def column(error)
+        message = error.message
+        (defined?(PG::PG_DIAG_COLUMN_NAME) && pg_error(error)&.result&.error_field(PG::PG_DIAG_COLUMN_NAME)) ||
+          message[/column "([^"]+)"/, 1] || message[/Column '([^']+)' cannot be null/, 1] ||
+          sqlite_column(message)
+      rescue StandardError
+        nil
+      end
+
+      def sqlite_column(message)
+        list = message[SQLITE_COLUMNS, 1] or return nil
+        list.split(", ").first.split(".").last
+      end
+
+      def pg_detail(error)
+        return nil unless defined?(PG::PG_DIAG_MESSAGE_DETAIL)
+
+        pg_error(error)&.result&.error_field(PG::PG_DIAG_MESSAGE_DETAIL)
+      end
+
+      # MySQL reports the index, not the column. `unique: true` on a column
+      # (what the generators write) names the index after the column; other
+      # indexes (table_column_index, composite) can't be mapped to one field.
+      def index_column(name)
+        name == "PRIMARY" || name.match?(/_(?:key|unique|uniq|index)\z/) ? [] : [name]
+      end
+    end
+  end
+end
+
+GemStack::DB::Errors.install!