planter 0.4.2 → 1.0.0

data/lib/planter/seeder.rb

@@ -4,30 +4,35 @@ module Planter
   ##
   # Class that seeders should inherit from. Seeders should be in +db/seeds+,
   # and named +TABLE_seeder.rb+, where +TABLE+ is the name of the table being
-  # seeded (I.E. +users_seeder.rb+). If your seeder is named differently than
-  # the table, you'll need to specify the table with the +model+ option. The
+  # seeded (for example, +users_seeder.rb+). If your seeder is named differently
+  # than the table, you'll need to specify the table with the +table+ option. The
   # seeder's class name should be the same as the file name, but camelized. So,
   # +UsersSeeder+. The directory where the seeder files are located can be
   # changed via an initializer.
   #
+  # To generate a seeder with a specific style, pass +--seeding-method=csv+,
+  # +--seeding-method=data-array+, or +--seeding-method=custom+ to
+  # +rails generate planter:seeder+. When the +csv+ method is used, the generator
+  # also creates a CSV file with headers pulled from the table.
+  #
   # The most basic way to seed is to have a CSV file with the same name as the
   # table in +db/seed_files/+. So, +users.csv+. This CSV should have the
-  # table's column names as header. To seed using this method, your class
-  # should look like the following. Note that +:csv_name+ and +:model+ are only
-  # required if your seeder or csv are named differently than the table being
+  # table's column names as headers. To seed using this method, your class
+  # should look like the following. Note that +:csv_name+ and +:table+ are only
+  # required if your seeder or CSV are named differently than the table being
   # seeded. The directory where the seed files are kept can be changed via an
   # initializer.
   #   # db/seeds/users_seeder.rb
   #   require 'planter'
   #   class UsersSeeder < Planter::Seeder
-  #     seeding_method :csv, csv_name: :users, model: 'User'
+  #     seeding_method :csv, csv_name: :users, table: :users
   #   end
   #
   # Another way to seed is to create records from a data array. To do this,
   # your class must implement a +data+ attribute or method, which is an array
   # of hashes. Note that this class already provides the +attr_reader+ for this
   # attribute, so the most you have to do is create instance variables in your
-  # constructor. If if you want your data to be different for each new record
+  # constructor. If you want your data to be different for each new record
   # (via Faker, +Array#sample+, etc.), you'll probably want to supply a method
   # called data that returns an array of new data each time.
   #   require 'planter'
@@ -39,13 +44,12 @@ module Planter
   #   end
   #
   # In both of the above methods, you can specify a +parent+ association, which
-  # is the +belongs_to+ association name in your model, which, when specified,
-  # records will be created for each record in the parent table. For example,
-  # if we're seeding the users table, and the model is +User+, which belongs to
-  # +Person+, then doing the following will create a user record for each
-  # record in the Person table. Note that nothing is automatically done to
-  # prevent any validation errors; you must do this on your own, mostly likely
-  # using +Faker+ or a similar library.
+  # is interpreted by the configured adapter. With the default Active Record
+  # adapter, +parent+ is the +belongs_to+ association name on a model-backed
+  # table. When specified, records will be created for each record in the parent
+  # table. Note that nothing is automatically done to prevent any validation
+  # errors; you must do this on your own, most likely using +Faker+ or a similar
+  # library.
   #   require 'planter'
   #   class UsersSeeder < Planter::Seeder
   #     seeding_method :data_array, parent: :person
@@ -55,7 +59,7 @@ module Planter
   #   end
   #
   # You can also set +number_of_records+ to determine how many times each
-  # record in the +data+ array will get created. The default is 1. Note that if
+  # record in the +data+ array will be created. The default is 1. Note that if
   # this attribute is set alongside +parent+, +number_of_records+ will be how
   # many records will be created for each record in the parent table.
   #   require 'planter'
@@ -68,7 +72,7 @@ module Planter
   #
   # By default, all fields are used to look up the record. If it already
   # exists, it is not re-created. If you have specific fields that a record
-  # should be looked-up by, you can pass the +unique_columns+ option. This will
+  # should be looked up by, you can pass the +unique_columns+ option. This will
   # attempt to look up the record by those fields only, and if one doesn't
   # exist, one will be created with the rest of the attributes. An example of
   # when this would be useful is with Devise; you can't pass +password+ in the
@@ -97,14 +101,14 @@ module Planter
     # attribute when using +data_array+ seeding method, although it's probably
     # more likely that you'll want to define a method that returns a new set of
     # data each time (via +Faker+, +Array#sample+, etc.). When using +csv+,
-    # +data+ will be set to the data within the csv. You can override this.
+    # +data+ will be set to the data within the CSV. You can override this.
     #
     # @return [Array]
     attr_reader :data
 
     ##
     # A hash of user-defined column names and procs to be run on values. This
-    # is most useful for when seeding from csv, and you need to transform, say,
+    # is most useful for when seeding from CSV, and you need to transform, say,
     # 'true' (String) into true (Boolean). The user may define this as an
     # instance variable, or define a method that returns the hash.
     #
@@ -145,16 +149,15 @@ module Planter
     class_attribute :unique_columns
 
     ##
-    # The model for the table being seeded. If the model name you need is
-    # different, change via +seeding_method+.
+    # The table being seeded. If the table name you need is different, change
+    # via +seeding_method+.
     #
     # @return [String]
-    class_attribute :model
+    class_attribute :table_name
 
     ##
-    # The model of the parent. When provided with +association+, records in the
-    # +data+ array, will be created for each record in the parent table. Your
-    # class must set this attribute via +seeding_method+.
+    # Adapter-defined parent relation. Records in the +data+ array will be
+    # created for each record in the parent relation.
     #
     # @return [String]
     class_attribute :parent
@@ -168,7 +171,7 @@ module Planter
     class_attribute :number_of_records
 
     ##
-    # The csv file corresponding to the model.
+    # The CSV file corresponding to the table.
     #
     # @return [String]
     class_attribute :csv_name
@@ -188,7 +191,7 @@ module Planter
     #
     # @kwarg [Integer] number_of_records
     #
-    # @kwarg [String] model
+    # @kwarg [String, Symbol] table
     #
     # @kwarg [Symbol, String] parent
     #
@@ -203,7 +206,7 @@ module Planter
     #   class UsersSeeder < Planter::Seeder
     #     seeding_method :csv,
     #       number_of_records: 2,
-    #       model: 'User'
+    #       table: :users
     #       parent: :person,
     #       csv_name: :awesome_users,
     #       unique_columns %i[username email],
@@ -212,7 +215,7 @@ module Planter
     def self.seeding_method(
       seed_method,
       number_of_records: 1,
-      model: nil,
+      table: nil,
       parent: nil,
       csv_name: nil,
       unique_columns: nil,
@@ -224,9 +227,9 @@ module Planter
 
       self.seed_method = seed_method
       self.number_of_records = number_of_records
-      self.model = model || to_s.delete_suffix("Seeder").singularize
+      self.table_name = (table || default_table_name).to_s
       self.parent = parent
-      self.csv_name = csv_name || to_s.delete_suffix("Seeder").underscore
+      self.csv_name = (csv_name || table_name).to_s
       self.erb_trim_mode = erb_trim_mode || Planter.config.erb_trim_mode
       self.unique_columns =
         case unique_columns
@@ -235,14 +238,22 @@ module Planter
         end
     end
 
+    ##
+    # Return the table name inferred from the seeder class name.
+    #
+    # @return [String]
+    def self.default_table_name
+      to_s.delete_suffix("Seeder").underscore
+    end
+
     ##
     # The default seed method. To use this method, your class must provide a
     # valid +seeding_method+, and not implement its own +seed+ method.
     def seed
       validate_attributes
-      extract_data_from_csv if seed_method == :csv
+      extract_data_from_csv if context.seed_method == :csv
 
-      parent ? create_records_from_parent : create_records
+      context.parent ? create_records_from_parent : create_records
     end
 
     private
@@ -250,7 +261,7 @@ module Planter
     ##
     # Creates records from the +data+ attribute.
     def create_records
-      number_of_records.times do
+      context.number_of_records.times do
         data.each { |record| create_record(record) }
       end
     end
@@ -258,48 +269,30 @@ module Planter
     ##
     # Create records from the +data+ attribute for each record in the +parent+.
     def create_records_from_parent
-      adapter.parent_ids(model_name: model, parent: parent).each do |parent_id|
-        number_of_records.times do
+      adapter.parent_ids(context: context).each do |parent_id|
+        context.number_of_records.times do
           data.each { |record| create_record(record, parent_id: parent_id) }
         end
       end
     end
 
     def create_record(record, parent_id: nil)
-      unique, attrs = split_record(apply_transformations(record))
-      unique = unique.merge(foreign_key => parent_id) if parent_id
-      unique, attrs = filter_lookup_attributes(unique, attrs)
+      lookup_attributes, create_attributes = record_attributes.prepare(record, parent_id: parent_id)
       adapter.create_record(
-        model_name: model,
-        lookup_attributes: unique,
-        create_attributes: attrs
+        context: context,
+        lookup_attributes: lookup_attributes,
+        create_attributes: create_attributes
       )
     end
 
-    def full_csv_name
-      @full_csv_name ||=
-        %W[#{csv_name}.csv #{csv_name}.csv.erb #{csv_name}.erb.csv]
-          .map { |f| Rails.root.join(Planter.config.csv_files_directory, f).to_s }
-          .find { |f| ::File.file?(f) }
-    end
-
     def extract_data_from_csv
-      contents = ::File.read(full_csv_name)
-      if full_csv_name.include?(".erb")
-        contents = ERB.new(contents, trim_mode: erb_trim_mode).result(binding)
-      end
-
-      @data ||= ::CSV.parse(
-        contents,
-        headers: true,
-        header_converters: :symbol
-      ).map(&:to_hash)
+      @data ||= csv_data_source.data
     end
 
     def validate_attributes # :nodoc:
-      case seed_method&.intern
+      case context.seed_method
       when :csv
-        raise "Couldn't find csv for #{model}" unless full_csv_name
+        raise "Couldn't find csv for #{context.table_name}" unless csv_data_source.path
       when :data_array
         raise "data is not defined in the seeder" if public_send(:data).nil?
       else
@@ -307,74 +300,30 @@ module Planter
       end
     end
 
-    def apply_transformations(record)
-      return record if public_send(:transformations).nil?
-
-      record.map { |field, value| map_record(field, value, record) }.to_h
-    end
-
-    def map_record(field, value, record)
-      [
-        field,
-        transformations.key?(field) ? transform(field, value, record) : value
-      ]
-    end
-
-    def transform(field, value, record)
-      case transformations[field].arity
-      when 0 then transformations[field].call
-      when 1 then transformations[field].call(value)
-      when 2 then transformations[field].call(value, record)
-      end
-    end
-
-    def split_record(rec) # :nodoc:
-      return [rec, {}] unless unique_columns
-
-      u = unique_columns.each_with_object({}) { |c, h| h[c] = rec[c] }
-      [u, rec.except(*unique_columns)]
+    def context
+      @context ||= Planter::SeedContext.new(
+        table_name: table_name,
+        seed_method: seed_method,
+        csv_name: csv_name,
+        parent: parent,
+        number_of_records: number_of_records,
+        unique_columns: unique_columns,
+        erb_trim_mode: erb_trim_mode
+      )
     end
 
-    def filter_lookup_attributes(lookup_attributes, create_attributes)
-      return [lookup_attributes, create_attributes] unless adapter.respond_to?(:table_columns)
-
-      table_columns = adapter.table_columns(model_name: model).map(&:to_s)
-      native_lookup_attributes = lookup_attributes.select do |field, _value|
-        table_columns.include?(field.to_s)
-      end
-      non_column_lookup_attributes = lookup_attributes.except(*native_lookup_attributes.keys)
-
-      if non_column_lookup_attributes.any?
-        warn_non_column_lookup_attributes(non_column_lookup_attributes.keys)
-      end
-
-      if native_lookup_attributes.empty?
-        raise "No native lookup columns found for #{model}. " \
-          "Add a native table column to the seed data or unique_columns."
-      end
-
-      [
-        native_lookup_attributes,
-        non_column_lookup_attributes.merge(create_attributes)
-      ]
+    def csv_data_source
+      @csv_data_source ||= Planter::CsvDataSource.new(context: context, seeder: self)
     end
 
-    def warn_non_column_lookup_attributes(fields)
-      warning_key = [model, fields.map(&:to_s).sort]
-      @warned_non_column_lookup_attributes ||= []
-      return if @warned_non_column_lookup_attributes.include?(warning_key)
-
-      @warned_non_column_lookup_attributes << warning_key
-      warn(
-        "WARNING: Planter moved non-column lookup attributes for #{model} " \
-        "into create attributes: #{warning_key.last.join(", ")}"
+    def record_attributes
+      @record_attributes ||= Planter::RecordAttributes.new(
+        context: context,
+        adapter: adapter,
+        transformations_provider: -> { public_send(:transformations) }
       )
     end
 
-    def foreign_key
-      adapter.foreign_key(model_name: model, parent: parent)
-    end
-
     def adapter
       Planter.config.adapter
     end

data/lib/planter/validator.rb

@@ -0,0 +1,296 @@
+# frozen_string_literal: true
+
+module Planter
+  ##
+  # Performs read-only validation of the configured seed plan.
+  #
+  # The validator checks that requested seeders can be loaded, that built-in
+  # seeding methods have the files or data they need, and that the configured
+  # adapter exposes Planter's public adapter API.
+  class Validator
+    ##
+    # Structured validation result containing fatal errors and non-fatal
+    # warnings.
+    class Result
+      ##
+      # Fatal validation errors.
+      #
+      # @return [Array<String>]
+      attr_reader :errors
+
+      ##
+      # Non-fatal validation warnings.
+      #
+      # @return [Array<String>]
+      attr_reader :warnings
+
+      ##
+      # Create an empty validation result.
+      def initialize
+        @errors = []
+        @warnings = []
+      end
+
+      ##
+      # Record a fatal validation error.
+      #
+      # @param message [String]
+      def add_error(message)
+        errors << message
+      end
+
+      ##
+      # Record a non-fatal validation warning.
+      #
+      # @param message [String]
+      def add_warning(message)
+        warnings << message
+      end
+
+      ##
+      # Whether validation completed without fatal errors.
+      #
+      # @return [Boolean]
+      def success?
+        errors.empty?
+      end
+    end
+
+    ##
+    # Adapter methods required for Planter's public adapter API.
+    #
+    # @return [Array<Symbol>]
+    REQUIRED_ADAPTER_METHODS = %i[
+      create_record
+      parent_ids
+      foreign_key
+      table_columns
+      table_names
+    ].freeze
+
+    ##
+    # Create a validator.
+    #
+    # @param config [Planter::Config]
+    #
+    # @param seeders [Array<String>, nil] seeders to validate
+    def initialize(config: Planter.config, seeders: nil)
+      @config = config
+      @seeders = seeders || requested_seeders
+      @result = Result.new
+    end
+
+    ##
+    # Validate the seed plan without creating, updating, or deleting records.
+    #
+    # @return [Planter::Validator::Result]
+    def validate
+      seeders_present = validate_seeders_present
+      validate_adapter
+      validate_seeders if seeders_present
+      result
+    end
+
+    private
+
+    attr_reader :config, :seeders, :result
+
+    def requested_seeders
+      ENV["SEEDERS"]&.split(",") || config.seeders&.map(&:to_s)
+    end
+
+    def validate_seeders_present
+      return true if seeders.present?
+
+      result.add_error(
+        "No seeders configured. Add seeders to config.seeders in " \
+        "config/initializers/planter.rb or set SEEDERS."
+      )
+      false
+    end
+
+    def validate_adapter
+      REQUIRED_ADAPTER_METHODS.each do |method|
+        next if adapter.respond_to?(method)
+
+        result.add_error("Configured adapter must respond to ##{method}.")
+      end
+    end
+
+    def validate_seeders
+      seeders.each { |seeder| validate_seeder(seeder) }
+    end
+
+    def validate_seeder(seeder)
+      return unless require_seeder(seeder)
+
+      seeder_class = constantize_seeder(seeder)
+      return unless seeder_class
+      return unless validate_seeder_class(seeder, seeder_class)
+      return if custom_seed?(seeder_class)
+
+      validate_default_seeder(seeder, seeder_class)
+    end
+
+    def require_seeder(seeder)
+      path = seeder_path(seeder)
+      unless ::File.file?(path)
+        result.add_error("Seeder file not found for #{seeder}: #{path}.")
+        return false
+      end
+
+      require path
+      true
+    rescue LoadError, SyntaxError, StandardError => error
+      result.add_error(
+        "Could not load seeder file for #{seeder}: #{error.class}: #{error.message}."
+      )
+      false
+    end
+
+    def constantize_seeder(seeder)
+      "#{seeder.camelize}Seeder".constantize
+    rescue NameError
+      result.add_error("Seeder class #{seeder.camelize}Seeder could not be constantized.")
+      nil
+    end
+
+    def validate_seeder_class(seeder, seeder_class)
+      return true if seeder_class <= Planter::Seeder
+
+      result.add_error("#{seeder.camelize}Seeder must inherit from Planter::Seeder.")
+      false
+    end
+
+    def custom_seed?(seeder_class)
+      seeder_class.instance_method(:seed).owner != Planter::Seeder
+    end
+
+    def validate_default_seeder(seeder, seeder_class)
+      unless Planter::Seeder::SEEDING_METHODS.include?(seeder_class.seed_method&.intern)
+        result.add_error("#{seeder.camelize}Seeder must define a valid seeding_method.")
+        return
+      end
+
+      case seeder_class.seed_method.intern
+      when :csv
+        validate_csv_seeder(seeder, seeder_class)
+      when :data_array
+        validate_data_array_seeder(seeder, seeder_class)
+      end
+    end
+
+    def validate_csv_seeder(seeder, seeder_class)
+      seeder_instance = build_seeder(seeder, seeder_class)
+      return unless seeder_instance
+
+      context = context_for(seeder_class)
+      data_source = Planter::CsvDataSource.new(context: context, seeder: seeder_instance)
+      unless data_source.path
+        result.add_error("CSV seed file not found for #{seeder_class.table_name}.")
+        return
+      end
+
+      return unless adapter.respond_to?(:table_columns)
+
+      validate_csv_headers(data_source.path, context, seeder_instance)
+    end
+
+    def validate_data_array_seeder(seeder, seeder_class)
+      seeder_instance = build_seeder(seeder, seeder_class)
+      return unless seeder_instance
+
+      return unless seeder_instance.public_send(:data).nil?
+
+      result.add_error("#{seeder.camelize}Seeder must define non-nil data.")
+    rescue => error
+      result.add_error(
+        "#{seeder.camelize}Seeder data could not be read: " \
+        "#{error.class}: #{error.message}."
+      )
+    end
+
+    def validate_csv_headers(path, context, seeder_instance)
+      headers = csv_headers(path, context, seeder_instance)
+      return if headers.nil?
+
+      table_columns = adapter.table_columns(context: context).map(&:to_s)
+      lookup_fields = csv_lookup_fields(headers, context)
+      native_lookup_fields = lookup_fields.select do |field|
+        table_columns.include?(field.to_s)
+      end
+      non_column_lookup_fields = lookup_fields - native_lookup_fields
+
+      if native_lookup_fields.empty?
+        result.add_error(
+          "No native lookup columns found for #{context.table_name}. " \
+          "Add a native table column to the seed data or unique_columns."
+        )
+      end
+
+      return if non_column_lookup_fields.empty?
+
+      result.add_warning(
+        "Planter will move non-column lookup attributes for #{context.table_name} " \
+        "into create attributes: #{non_column_lookup_fields.map(&:to_s).sort.join(", ")}."
+      )
+    rescue => error
+      result.add_error(
+        "CSV headers could not be read for #{context.table_name}: " \
+        "#{error.class}: #{error.message}."
+      )
+    end
+
+    def csv_headers(path, context, seeder_instance)
+      header = ::File.foreach(path).first.to_s
+      if path.include?(".erb") && header.include?("<%")
+        header = ERB.new(header, trim_mode: context.erb_trim_mode).result(
+          seeder_instance.instance_eval { binding }
+        )
+      end
+
+      ::CSV.parse(header, headers: true, header_converters: :symbol).headers
+    end
+
+    def csv_lookup_fields(headers, context)
+      fields = context.unique_columns || headers
+      fields = fields.compact.map(&:to_sym)
+
+      if context.parent && adapter.respond_to?(:foreign_key)
+        fields << adapter.foreign_key(context: context).to_sym
+      end
+
+      fields
+    end
+
+    def build_seeder(seeder, seeder_class)
+      seeder_class.new
+    rescue => error
+      result.add_error(
+        "#{seeder.camelize}Seeder could not be initialized: " \
+        "#{error.class}: #{error.message}."
+      )
+      nil
+    end
+
+    def context_for(seeder_class)
+      Planter::SeedContext.new(
+        table_name: seeder_class.table_name,
+        seed_method: seeder_class.seed_method,
+        csv_name: seeder_class.csv_name,
+        parent: seeder_class.parent,
+        number_of_records: seeder_class.number_of_records,
+        unique_columns: seeder_class.unique_columns,
+        erb_trim_mode: seeder_class.erb_trim_mode
+      )
+    end
+
+    def seeder_path(seeder)
+      Rails.root.join(config.seeders_directory, "#{seeder}_seeder.rb").to_s
+    end
+
+    def adapter
+      @adapter ||= config.adapter
+    end
+  end
+end

data/lib/planter/version.rb

@@ -9,19 +9,19 @@ module Planter
     # Major version.
     #
     # @return [Integer]
-    MAJOR = 0
+    MAJOR = 1
 
     ##
     # Minor version.
     #
     # @return [Integer]
-    MINOR = 4
+    MINOR = 0
 
     ##
     # Patch version.
     #
     # @return [Integer]
-    PATCH = 2
+    PATCH = 0
 
     module_function