planter 0.5.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eb6405a71e2d12a6f934ba4715d5166f1fba3eac5034dd22c1fe0b98f9b3ec07
-  data.tar.gz: 4680be7ea150b89db17372e9da80b855e39ca4702bc8067f71fa3b6c6cbc0698
+  metadata.gz: b66f9b16f720b193d4dee6e0a23382b22a073982634bccbad2d52092516090eb
+  data.tar.gz: 5d66d7905379b7b148586b52b85afb2d715501543e88f0d84a88973b734d9f6b
 SHA512:
-  metadata.gz: 22dcb8b7683e1bbcfeb186c62d6250b36b7882271bba2d8e062c845a877225eefe117eef27b28a2c419a1ef860e19ff563c944b04998383b3c6551c075ee0844
-  data.tar.gz: 93b858d71f6f32324648d1fcd85604b373bc8f4a69601a445891eb81330b41413afdda8dc5c08526bd45bd1c7601f17ef9b1e93dc50ceb4ed67c05ba69b83921
+  metadata.gz: dde579bb6c055ce0c819148d1d818b39bf44ef9e75c692799dd760c7f9a96a0828d959f3204e6741fa55c41a6b9c2d8045f746142c139b5f20f1ea450ba7b259
+  data.tar.gz: 9f208c04796ae9f80ce6d46b4ec94e56da4fc2c62c36abf3198d806621bf2c7d79d9f52fd2d30ad0ee73c94206e7f0997b953ff93dbc93b83ff8064ee7ab85ed

data/README.md

@@ -18,12 +18,10 @@ Features include:
 You can view the documentation [here](https://evanthegrayt.github.io/planter/).
 
 ## Installation
-Add the following line to your application's Gemfile. Because this plugin is
-currently a pre-release version, it's recommended to lock it to a specific
-version, as breaking changes may occur, even at the minor level.
+Add the following line to your application's Gemfile.
 
 ```ruby
-gem 'planter', '0.5.0'
+gem 'planter'
 ```
 
 And then execute:
@@ -97,6 +95,25 @@ into the existing `db:seed` task, simply add the following to `db/seeds.rb`.
 Planter.seed
 ```
 
+Before seeding, you can validate your Planter configuration without creating
+records.
+
+```bash
+rails planter:validate
+```
+
+This command loads the Rails environment, checks the configured seeders, and
+verifies that the configured adapter exposes Planter's adapter API. It prints a
+success message when no issues are found, warnings for non-fatal issues, and
+errors before exiting non-zero when the seed plan is not valid.
+
+Like `planter:seed`, validation supports the `SEEDERS` environment variable if
+you want to check only part of the configured plan.
+
+```bash
+rails planter:validate SEEDERS=users,addresses
+```
+
 To create a users seeder, run `rails generate planter:seeder users`. Usually,
 seeders seed a specific table, so it's recommended to name your seeders after
 the table. If you don't, specify the table with the `table` option in

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,13 +9,13 @@ module Planter
     # Major version.
     #
     # @return [Integer]
-    MAJOR = 0
+    MAJOR = 1
 
     ##
     # Minor version.
     #
     # @return [Integer]
-    MINOR = 5
+    MINOR = 0
 
     ##
     # Patch version.

data/lib/planter.rb

@@ -9,6 +9,7 @@ require "planter/seed_context"
 require "planter/csv_data_source"
 require "planter/record_attributes"
 require "planter/seeder"
+require "planter/validator"
 
 ##
 # The main module for the plugin. It nicely wraps the +Planter::Config+ class
@@ -83,4 +84,14 @@ module Planter
       "#{s.camelize}Seeder".constantize.new.seed
     end
   end
+
+  ##
+  # Validate the configured seed plan without creating records. This checks
+  # seeder files, seeder classes, built-in seeding method configuration, CSV
+  # headers where possible, and the configured adapter API.
+  #
+  # @return [Planter::Validator::Result]
+  def validate
+    Planter::Validator.new.validate
+  end
 end

data/lib/tasks/planter_tasks.rake

@@ -1,13 +1,39 @@
 require "planter"
 
 namespace :planter do
+  apply_directory_overrides = lambda do
+    if ENV["SEEDERS_DIRECTORY"]
+      Planter.config.seeders_directory = ENV["SEEDERS_DIRECTORY"]
+    end
+
+    if ENV["CSV_FILES_DIRECTORY"]
+      Planter.config.csv_files_directory = ENV["CSV_FILES_DIRECTORY"]
+    end
+  end
+
   desc "Seed application. Use this to keep planter separate from db:seed"
   task seed: :environment do
-    Planter.configure do |config|
-      # NOTE: the seed method already looks for ENV['SEEDERS']
-      ENV["SEEDERS_DIRECTORY"] && config.seeders_directory = ENV["SEEDERS_DIRECTORY"]
-      ENV["CSV_FILES_DIRECTORY"] && config.csv_files_directory = ENV["CSV_FILES_DIRECTORY"]
-    end
+    # NOTE: the seed method already looks for ENV['SEEDERS']
+    apply_directory_overrides.call
     Planter.seed
   end
+
+  desc "Validate Planter configuration without creating records"
+  task validate: :environment do
+    apply_directory_overrides.call
+    result = Planter.validate
+
+    result.warnings.each { |warning| warn "WARNING: #{warning}" }
+    result.errors.each { |error| warn "ERROR: #{error}" }
+
+    if result.success?
+      puts(
+        result.warnings.empty? ?
+          "Planter validation passed." :
+          "Planter validation completed with warnings."
+      )
+    else
+      abort "Planter validation failed."
+    end
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: planter
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Evan Gray
@@ -107,6 +107,7 @@ files:
 - lib/planter/record_attributes.rb
 - lib/planter/seed_context.rb
 - lib/planter/seeder.rb
+- lib/planter/validator.rb
 - lib/planter/version.rb
 - lib/tasks/planter_tasks.rake
 homepage: https://github.com/evanthegrayt/planter