importu 0.1.0 → 0.2.0

data/gemfiles/standalone.gemfile.lock

@@ -0,0 +1,197 @@
+PATH
+  remote: ..
+  specs:
+    importu (0.1.0)
+      bigdecimal
+      csv
+      nokogiri (>= 1.13)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    appraisal (2.5.0)
+      bundler
+      rake
+      thor (>= 0.14.0)
+    ast (2.4.3)
+    bigdecimal (4.0.1)
+    csv (3.3.5)
+    date (3.5.1)
+    diff-lcs (1.6.2)
+    docile (1.4.1)
+    erb (6.0.1)
+    io-console (0.8.2)
+    irb (1.16.0)
+      pp (>= 0.6.0)
+      rdoc (>= 4.0.0)
+      reline (>= 0.4.2)
+    json (2.18.0)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
+    nokogiri (1.19.0-aarch64-linux-gnu)
+      racc (~> 1.4)
+    nokogiri (1.19.0-aarch64-linux-musl)
+      racc (~> 1.4)
+    nokogiri (1.19.0-arm-linux-gnu)
+      racc (~> 1.4)
+    nokogiri (1.19.0-arm-linux-musl)
+      racc (~> 1.4)
+    nokogiri (1.19.0-arm64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.19.0-x86_64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.19.0-x86_64-linux-gnu)
+      racc (~> 1.4)
+    nokogiri (1.19.0-x86_64-linux-musl)
+      racc (~> 1.4)
+    parallel (1.27.0)
+    parser (3.3.10.1)
+      ast (~> 2.4.1)
+      racc
+    pp (0.6.3)
+      prettyprint
+    prettyprint (0.2.0)
+    prism (1.9.0)
+    psych (5.3.1)
+      date
+      stringio
+    racc (1.8.1)
+    rainbow (3.1.1)
+    rake (13.3.1)
+    rdoc (7.1.0)
+      erb
+      psych (>= 4.0.0)
+      tsort
+    redcarpet (3.6.1)
+    regexp_parser (2.11.3)
+    reline (0.6.3)
+      io-console (~> 0.5)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.7)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.6)
+    rubocop (1.84.0)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.49.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    rubocop-performance (1.26.1)
+      lint_roller (~> 1.1)
+      rubocop (>= 1.75.0, < 2.0)
+      rubocop-ast (>= 1.47.1, < 2.0)
+    ruby-progressbar (1.13.0)
+    simplecov (0.22.0)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.13.2)
+    simplecov_json_formatter (0.1.4)
+    stringio (3.2.0)
+    thor (1.5.0)
+    tsort (0.2.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
+    yard (0.9.38)
+    yardstick (0.9.9)
+      yard (~> 0.8, >= 0.8.7.2)
+
+PLATFORMS
+  aarch64-linux-gnu
+  aarch64-linux-musl
+  arm-linux-gnu
+  arm-linux-musl
+  arm64-darwin
+  x86_64-darwin
+  x86_64-linux-gnu
+  x86_64-linux-musl
+
+DEPENDENCIES
+  appraisal
+  bundler (>= 2.0)
+  importu!
+  irb
+  redcarpet
+  rspec (~> 3.13)
+  rubocop (~> 1.70)
+  rubocop-performance (~> 1.24)
+  simplecov (~> 0.22)
+  yard
+  yardstick (~> 0.9)
+
+CHECKSUMS
+  appraisal (2.5.0) sha256=36989221be127913b0dba8d114da2001e6b2dceea7bd4951200eaba764eed3ce
+  ast (2.4.3) sha256=954615157c1d6a382bc27d690d973195e79db7f55e9765ac7c481c60bdb4d383
+  bigdecimal (4.0.1) sha256=8b07d3d065a9f921c80ceaea7c9d4ae596697295b584c296fe599dd0ad01c4a7
+  csv (3.3.5) sha256=6e5134ac3383ef728b7f02725d9872934f523cb40b961479f69cf3afa6c8e73f
+  date (3.5.1) sha256=750d06384d7b9c15d562c76291407d89e368dda4d4fff957eb94962d325a0dc0
+  diff-lcs (1.6.2) sha256=9ae0d2cba7d4df3075fe8cd8602a8604993efc0dfa934cff568969efb1909962
+  docile (1.4.1) sha256=96159be799bfa73cdb721b840e9802126e4e03dfc26863db73647204c727f21e
+  erb (6.0.1) sha256=28ecdd99c5472aebd5674d6061e3c6b0a45c049578b071e5a52c2a7f13c197e5
+  importu (0.1.0)
+  io-console (0.8.2) sha256=d6e3ae7a7cc7574f4b8893b4fca2162e57a825b223a177b7afa236c5ef9814cc
+  irb (1.16.0) sha256=2abe56c9ac947cdcb2f150572904ba798c1e93c890c256f8429981a7675b0806
+  json (2.18.0) sha256=b10506aee4183f5cf49e0efc48073d7b75843ce3782c68dbeb763351c08fd505
+  language_server-protocol (3.17.0.5) sha256=fd1e39a51a28bf3eec959379985a72e296e9f9acfce46f6a79d31ca8760803cc
+  lint_roller (1.1.0) sha256=2c0c845b632a7d172cb849cc90c1bce937a28c5c8ccccb50dfd46a485003cc87
+  nokogiri (1.19.0-aarch64-linux-gnu) sha256=11a97ecc3c0e7e5edcf395720b10860ef493b768f6aa80c539573530bc933767
+  nokogiri (1.19.0-aarch64-linux-musl) sha256=eb70507f5e01bc23dad9b8dbec2b36ad0e61d227b42d292835020ff754fb7ba9
+  nokogiri (1.19.0-arm-linux-gnu) sha256=572a259026b2c8b7c161fdb6469fa2d0edd2b61cd599db4bbda93289abefbfe5
+  nokogiri (1.19.0-arm-linux-musl) sha256=23ed90922f1a38aed555d3de4d058e90850c731c5b756d191b3dc8055948e73c
+  nokogiri (1.19.0-arm64-darwin) sha256=0811dfd936d5f6dd3f6d32ef790568bf29b2b7bead9ba68866847b33c9cf5810
+  nokogiri (1.19.0-x86_64-darwin) sha256=1dad56220b603a8edb9750cd95798bffa2b8dd9dd9aa47f664009ee5b43e3067
+  nokogiri (1.19.0-x86_64-linux-gnu) sha256=f482b95c713d60031d48c44ce14562f8d2ce31e3a9e8dd0ccb131e9e5a68b58c
+  nokogiri (1.19.0-x86_64-linux-musl) sha256=1c4ca6b381622420073ce6043443af1d321e8ed93cc18b08e2666e5bd02ffae4
+  parallel (1.27.0) sha256=4ac151e1806b755fb4e2dc2332cbf0e54f2e24ba821ff2d3dcf86bf6dc4ae130
+  parser (3.3.10.1) sha256=06f6a725d2cd91e5e7f2b7c32ba143631e1f7c8ae2fb918fc4cebec187e6a688
+  pp (0.6.3) sha256=2951d514450b93ccfeb1df7d021cae0da16e0a7f95ee1e2273719669d0ab9df6
+  prettyprint (0.2.0) sha256=2bc9e15581a94742064a3cc8b0fb9d45aae3d03a1baa6ef80922627a0766f193
+  prism (1.9.0) sha256=7b530c6a9f92c24300014919c9dcbc055bf4cdf51ec30aed099b06cd6674ef85
+  psych (5.3.1) sha256=eb7a57cef10c9d70173ff74e739d843ac3b2c019a003de48447b2963d81b1974
+  racc (1.8.1) sha256=4a7f6929691dbec8b5209a0b373bc2614882b55fc5d2e447a21aaa691303d62f
+  rainbow (3.1.1) sha256=039491aa3a89f42efa1d6dec2fc4e62ede96eb6acd95e52f1ad581182b79bc6a
+  rake (13.3.1) sha256=8c9e89d09f66a26a01264e7e3480ec0607f0c497a861ef16063604b1b08eb19c
+  rdoc (7.1.0) sha256=494899df0706c178596ca6e1d50f1b7eb285a9b2aae715be5abd742734f17363
+  redcarpet (3.6.1) sha256=d444910e6aa55480c6bcdc0cdb057626e8a32c054c29e793fa642ba2f155f445
+  regexp_parser (2.11.3) sha256=ca13f381a173b7a93450e53459075c9b76a10433caadcb2f1180f2c741fc55a4
+  reline (0.6.3) sha256=1198b04973565b36ec0f11542ab3f5cfeeec34823f4e54cebde90968092b1835
+  rspec (3.13.2) sha256=206284a08ad798e61f86d7ca3e376718d52c0bc944626b2349266f239f820587
+  rspec-core (3.13.6) sha256=a8823c6411667b60a8bca135364351dda34cd55e44ff94c4be4633b37d828b2d
+  rspec-expectations (3.13.5) sha256=33a4d3a1d95060aea4c94e9f237030a8f9eae5615e9bd85718fe3a09e4b58836
+  rspec-mocks (3.13.7) sha256=0979034e64b1d7a838aaaddf12bf065ea4dc40ef3d4c39f01f93ae2c66c62b1c
+  rspec-support (3.13.6) sha256=2e8de3702427eab064c9352fe74488cc12a1bfae887ad8b91cba480ec9f8afb2
+  rubocop (1.84.0) sha256=88dec310153bb685a879f5a7cdb601f6287b8f0ee675d9dc63a17c7204c4190a
+  rubocop-ast (1.49.0) sha256=49c3676d3123a0923d333e20c6c2dbaaae2d2287b475273fddee0c61da9f71fd
+  rubocop-performance (1.26.1) sha256=cd19b936ff196df85829d264b522fd4f98b6c89ad271fa52744a8c11b8f71834
+  ruby-progressbar (1.13.0) sha256=80fc9c47a9b640d6834e0dc7b3c94c9df37f08cb072b7761e4a71e22cff29b33
+  simplecov (0.22.0) sha256=fe2622c7834ff23b98066bb0a854284b2729a569ac659f82621fc22ef36213a5
+  simplecov-html (0.13.2) sha256=bd0b8e54e7c2d7685927e8d6286466359b6f16b18cb0df47b508e8d73c777246
+  simplecov_json_formatter (0.1.4) sha256=529418fbe8de1713ac2b2d612aa3daa56d316975d307244399fa4838c601b428
+  stringio (3.2.0) sha256=c37cb2e58b4ffbd33fe5cd948c05934af997b36e0b6ca6fdf43afa234cf222e1
+  thor (1.5.0) sha256=e3a9e55fe857e44859ce104a84675ab6e8cd59c650a49106a05f55f136425e73
+  tsort (0.2.0) sha256=9650a793f6859a43b6641671278f79cfead60ac714148aabe4e3f0060480089f
+  unicode-display_width (3.2.0) sha256=0cdd96b5681a5949cdbc2c55e7b420facae74c4aaf9a9815eee1087cb1853c42
+  unicode-emoji (4.2.0) sha256=519e69150f75652e40bf736106cfbc8f0f73aa3fb6a65afe62fefa7f80b0f80f
+  yard (0.9.38) sha256=721fb82afb10532aa49860655f6cc2eaa7130889df291b052e1e6b268283010f
+  yardstick (0.9.9) sha256=c39a166a9a37c0b164dc1969c8e20fe158061079e97c95454ceb58d0515ec06e
+
+BUNDLED WITH
+  4.0.3

data/importu.gemspec

@@ -1,29 +1,48 @@
-$LOAD_PATH.unshift File.expand_path('../lib', __FILE__)
-require 'importu/version'
+# frozen_string_literal: true
+$LOAD_PATH.unshift File.expand_path("lib", __dir__)
+require "importu/version"
 
 Gem::Specification.new do |s|
-  s.name        = 'importu'
+  s.name        = "importu"
   s.version     = Importu::VERSION
   s.platform    = Gem::Platform::RUBY
-  s.authors     = ['Daniel Hedlund']
-  s.email       = ['daniel@lincracy.com']
-  s.homepage    = 'https://github.com/lincracy/importu'
-  s.summary     = 'A framework for importing data'
-  s.description = 'Importu is a framework for importing data'
+  s.required_ruby_version = ">= 3.1"
+  s.authors     = ["Daniel Hedlund"]
+  s.email       = ["daniel@digitree.org"]
+  s.homepage    = "https://github.com/dhedlund/importu"
+  s.summary     = "Because an import should be defined by a contract, not " +
+                  "a sequence of commands"
+  s.description = "Importu simplifies the process of defining and sharing " +
+                  "contracts that structured data must conform to in order " +
+                  "to be importable into your application."
 
   s.files            = `git ls-files`.split("\n")
-  s.test_files       = `git ls-files -- {test,spec,features}/*`.split("\n")
-  s.require_paths    = ['lib']
-
-  s.licenses = ['MIT']
-  
-  s.add_dependency 'activesupport', ['>= 3.0.0']
-  s.add_dependency 'activerecord',  ['>= 3.0.0']
-  s.add_dependency 'multi_json',    ['~> 1.0']
-  s.add_dependency 'nokogiri'
-
-  s.add_development_dependency 'bundler',      ['>= 1.0.0']
-  s.add_development_dependency 'rspec',        ['>= 0']
-  s.add_development_dependency 'rdoc',         ['>= 0']
-  s.add_development_dependency 'factory_girl', ['>= 3.5.0']
+  s.require_paths    = ["lib"]
+
+  s.licenses = ["MIT"]
+
+  s.metadata = {
+    "homepage_uri"    => s.homepage,
+    "source_code_uri" => s.homepage,
+    "changelog_uri"   => "#{s.homepage}/blob/master/CHANGELOG.md",
+    "bug_tracker_uri" => "#{s.homepage}/issues",
+  }
+
+  s.add_dependency "bigdecimal"
+  s.add_dependency "csv"
+  s.add_dependency "nokogiri", ">= 1.18.4"
+
+  s.add_development_dependency "appraisal"
+  s.add_development_dependency "bundler",      ">= 2.0"
+  s.add_development_dependency "rspec",        "~> 3.13"
+  s.add_development_dependency "simplecov",    "~> 0.22"
+
+  # Code Quality
+  s.add_development_dependency "rubocop", "~> 1.70"
+  s.add_development_dependency "rubocop-performance", "~> 1.24"
+
+  # YARD Documentation
+  s.add_development_dependency "redcarpet" # For README.md
+  s.add_development_dependency "yard"
+
 end

data/lib/importu/backends/active_record.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+require "importu/backends"
+require "importu/exceptions"
+
+# Backend for persisting records to ActiveRecord models.
+#
+# This backend is automatically registered and detected when your model
+# inherits from ActiveRecord::Base.
+#
+# @example Basic usage in an importer
+#   class BookImporter < Importu::Importer
+#     model "Book"
+#     allow_actions :create, :update
+#     find_by :isbn
+#   end
+#
+# @api semipublic
+class Importu::Backends::ActiveRecord
+  # Checks if this backend supports the given model.
+  #
+  # @param model [Class] the model class
+  # @return [Boolean] true if model inherits from ActiveRecord::Base
+  def self.supported_by_model?(model)
+    model < ActiveRecord::Base # Inherits from
+  end
+
+  # Creates a new ActiveRecord backend.
+  #
+  # @param model [Class, String] the ActiveRecord model class or name
+  # @param finder_fields [Array] field groups for finding existing records
+  # @param before_save [Proc, nil] optional callback before saving
+  # @api private
+  def initialize(model:, finder_fields:, before_save: nil, **)
+    @model = model.is_a?(String) ? self.class.const_get(model) : model
+    @finder_fields = finder_fields
+    @before_save = before_save
+  end
+
+  # Finds an existing record matching the import data.
+  #
+  # @param record [Importu::Record] the import record
+  # @return [ActiveRecord::Base, nil] the matching record or nil
+  def find(record)
+    @finder_fields.each do |field_group|
+      if field_group.respond_to?(:call) # proc
+        object = @model.instance_exec(record, &field_group)
+      else
+        conditions = field_group.to_h {|f| [f, record[f]]}
+        object = @model.where(conditions).first
+      end
+
+      return object if object
+    end
+
+    nil
+  end
+
+  # The unique id representing the object in the database, if one exists.
+  def unique_id(object)
+    object.respond_to?(:id) ? object.id : nil
+  end
+
+  # Creates a new record in the database.
+  #
+  # @param record [Importu::Record] the import record
+  # @return [Array<(Symbol, ActiveRecord::Base)>] status and object
+  # @raise [Importu::InvalidRecord] if validation fails
+  def create(record)
+    object = @model.new
+    perform_assignment(record, object, :create)
+    save(record, object)
+  end
+
+  # Updates an existing record in the database.
+  #
+  # @param record [Importu::Record] the import record
+  # @param object [ActiveRecord::Base] the existing record
+  # @return [Array<(Symbol, ActiveRecord::Base)>] status and object
+  # @raise [Importu::InvalidRecord] if validation fails
+  def update(record, object)
+    perform_assignment(record, object, :update)
+    save(record, object)
+  end
+
+  private def perform_assignment(record, object, action)
+    AssignmentContext.new(record, object, action).tap do |context|
+      context.assign_values
+      context.apply(&@before_save)
+    end
+  end
+
+  private def save(_record, object)
+    return [:unchanged, object] unless object.changed?
+    new_record = object.new_record?
+
+    begin
+      object.save!
+    rescue ActiveRecord::RecordInvalid
+      error_msgs = object.errors.map do |error|
+        error.attribute == :base ? error.message : "#{error.attribute} #{error.message}"
+      end
+
+      # Normalize messages by stripping trailing parenthesized data (e.g., "(value: foo)")
+      # This allows similar errors to be aggregated in the Summary.
+      normalized_msgs = error_msgs.map { |msg| msg.gsub(/ *\([^)]+\) *$/, "") }
+
+      raise Importu::InvalidRecord.new(
+        error_msgs.join(", "),
+        object.errors.full_messages,
+        normalized_message: normalized_msgs.join(", ")
+      )
+    end
+
+    [(new_record ? :created : :updated), object]
+  end
+
+  # Context for assigning field values to a model instance.
+  #
+  # This is the execution context for before_save hooks, providing access
+  # to the record data, model object, and current action.
+  #
+  # @api semipublic
+  class AssignmentContext
+    # @return [Importu::Record] the import record
+    attr_reader :record
+
+    # @return [ActiveRecord::Base] the model instance
+    attr_reader :object
+
+    # @return [Symbol] the action (:create or :update)
+    attr_reader :action
+
+    # @api private
+    def initialize(record, object, action)
+      @record, @object, @action = record, object, action
+    end
+
+    # Executes a block in this context.
+    #
+    # @yield block to execute with access to record, object, and action
+    # @api private
+    def apply(&block)
+      instance_eval(&block) if block
+    end
+
+    # Assigns field values from the record to the object.
+    #
+    # @raise [Importu::UnassignableFields] if fields cannot be assigned
+    # @api private
+    def assign_values
+      field_names = record.assignable_fields_for(action)
+
+      begin
+        field_names.each do |name|
+          object.send("#{name}=", record[name])
+        end
+      rescue NoMethodError
+        raise_unassignable_fields!(field_names)
+      end
+    end
+
+    private def raise_unassignable_fields!(field_names)
+      unassignable = field_names.reject {|n| object.respond_to?("#{n}=") }
+      raise Importu::UnassignableFields, "model does not support assigning " +
+        "all fields: " + unassignable.join(", ")
+    end
+  end
+
+end
+
+Importu::Backends.registry.register(:active_record, Importu::Backends::ActiveRecord)

data/lib/importu/backends/middleware/duplicate_manager_proxy.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+require "delegate"
+
+require "importu/backends/middleware"
+require "importu/duplicate_manager"
+
+# Wraps any model-based backend adapter to provide duplicate detection.
+class Importu::Backends::Middleware::DuplicateManagerProxy < SimpleDelegator
+
+  def initialize(backend, finder_fields:, **)
+    super(backend)
+    @manager = Importu::DuplicateManager.new(finder_fields: finder_fields)
+  end
+
+  # Before passing to the backend for create, make sure the record is not
+  # a duplicate by using the finder field information that is available.
+  # When creating a new object, we will need to record that object as
+  # encountered as soon as it has been given a unique id. Any updates
+  # to that record within the same import will be treated as duplicate.
+  def create(record)
+    @manager.check_record!(record)
+
+    result, object = super
+
+    # Record the newly created object as encountered
+    @manager.check_object!(unique_id(object))
+
+    [result, object]
+  end
+
+  # Before passing to the backend for update, make sure the record is not
+  # a duplicate by using the finder field information that is available.
+  # Also check the object's unique identifier to ensure we have not already
+  # tried to change the object from a previous record import.
+  def update(record, object)
+    @manager.check_record!(record)
+    @manager.check_object!(unique_id(object))
+    super
+  end
+
+end

data/lib/importu/backends/middleware/enforce_allowed_actions.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+require "delegate"
+
+require "importu/backends/middleware"
+require "importu/exceptions"
+
+# Middleware that enforces allowed actions on a backend.
+#
+# Wraps a backend and raises InvalidRecord if a create or update action
+# is attempted that isn't in the allowed_actions list.
+#
+# @api private
+class Importu::Backends::Middleware::EnforceAllowedActions < SimpleDelegator
+  # Creates middleware wrapping the given backend.
+  #
+  # @param backend [Object] the backend to wrap
+  # @param allowed_actions [Array<Symbol>] actions that are permitted
+  def initialize(backend, allowed_actions:, **)
+    super(backend)
+    @allowed_actions = allowed_actions
+  end
+
+  # Creates a record, if create action is allowed.
+  #
+  # @param record [Importu::Record] the import record
+  # @return [Array] status and object from wrapped backend
+  # @raise [Importu::InvalidRecord] if create not allowed
+  def create(record)
+    if @allowed_actions.include?(:create)
+      super
+    else
+      raise Importu::InvalidRecord,
+            "create action not allowed; add `allow_actions :create` to your importer"
+    end
+  end
+
+  # Updates a record, if update action is allowed.
+  #
+  # @param record [Importu::Record] the import record
+  # @param object [Object] the existing record
+  # @return [Array] status and object from wrapped backend
+  # @raise [Importu::InvalidRecord] if update not allowed
+  def update(record, object)
+    if @allowed_actions.include?(:update)
+      super
+    else
+      raise Importu::InvalidRecord,
+            "update action not allowed; add `allow_actions :create, :update` to your importer"
+    end
+  end
+
+end

data/lib/importu/backends/middleware.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+class Importu::Backends
+  # Namespace for backend middleware.
+  #
+  # Middleware wraps backends to add cross-cutting behavior like enforcing
+  # allowed actions and detecting duplicates within an import.
+  #
+  # @api private
+  module Middleware
+  end
+end

data/lib/importu/backends.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+require "importu/backends/middleware/enforce_allowed_actions"
+require "importu/backends/middleware/duplicate_manager_proxy"
+require "importu/exceptions"
+
+# Registry for persistence backends.
+#
+# Backends handle persisting imported records to a data store. The registry
+# allows registering custom backends and auto-detecting which backend to use
+# based on the model class.
+#
+# @example Registering a custom backend
+#   Importu::Backends.registry.register(:sequel, MySequelBackend)
+#
+# @example Looking up a backend
+#   backend_class = Importu::Backends.registry.lookup(:active_record)
+#
+# @api semipublic
+class Importu::Backends
+  # Returns the middleware classes applied to all backends.
+  #
+  # @return [Array<Class>] middleware classes in application order
+  def self.middleware
+    [
+      Importu::Backends::Middleware::EnforceAllowedActions,
+      Importu::Backends::Middleware::DuplicateManagerProxy,
+    ]
+  end
+
+  # Returns the global backend registry instance.
+  #
+  # @return [Importu::Backends] the singleton registry
+  def self.registry
+    @registry ||= new
+  end
+
+  # Creates a new backend registry.
+  #
+  # @api private
+  def initialize
+    @registered = Hash.new do |_hash, key|
+      raise Importu::BackendNotRegistered, key
+    end
+  end
+
+  # Resolves a backend class from importer configuration.
+  #
+  # @param name [Symbol, nil] explicit backend name, :auto, or nil for auto-detect
+  # @param model [Class, String] the model class or class name
+  # @return [Class] the backend class
+  # @raise [Importu::BackendNotRegistered] if named backend not found
+  # @raise [Importu::BackendMatchError] if auto-detection fails
+  def from_config!(name:, model:, **)
+    model = model.is_a?(String) ? self.class.const_get(model) : model
+    # Support :auto as an explicit way to request auto-detection (same as nil)
+    name && name != :auto ? lookup(name) : detect_from_model(model)
+  end
+
+  # Looks up a backend by name.
+  #
+  # @param name [Symbol, String] the backend name
+  # @return [Class] the backend class
+  # @raise [Importu::BackendNotRegistered] if not found
+  def lookup(name)
+    @registered[name.to_sym]
+  end
+
+  # Returns all registered backend names.
+  #
+  # @return [Array<Symbol>] registered backend names
+  def names
+    @registered.keys
+  end
+
+  # Registers a backend class.
+  #
+  # @param name [Symbol, String] the backend name
+  # @param klass [Class] the backend class
+  # @return [Class] the registered class
+  def register(name, klass)
+    @registered[name.to_sym] = klass
+  end
+
+  private def detect_from_model(model)
+    matched = @registered.select do |_name, backend|
+      backend.supported_by_model?(model) rescue false
+    end
+
+    if matched.one?
+      matched.values.first
+    elsif matched.none?
+      raise Importu::BackendMatchError, "No backends detected from importer " +
+        "model. Try adding `backend: :mybackend` to your model definition. " +
+        "Known values are: " + names.map {|v| ":#{v}"}.join(", ")
+    else
+      raise Importu::BackendMatchError, "Backend auto-detection is " +
+        "ambiguous, multiple candidates match. Try adding `backend: " +
+        ":mybackend` to your model definition. Matched backends are: " +
+        matched.keys.map {|v| ":#{v}"}.join(", ")
+    end
+  end
+
+end