planter 0.5.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eb6405a71e2d12a6f934ba4715d5166f1fba3eac5034dd22c1fe0b98f9b3ec07
-  data.tar.gz: 4680be7ea150b89db17372e9da80b855e39ca4702bc8067f71fa3b6c6cbc0698
+  metadata.gz: d5ec6b0fc5c0ec804e4a1ea2f1c050bcad9eadcc4cea08a8816a6b3ff17a1c37
+  data.tar.gz: 3639096bccfaf6aac225c78c7acfc919610802f4569fa239ffe4ffe7b648edcc
 SHA512:
-  metadata.gz: 22dcb8b7683e1bbcfeb186c62d6250b36b7882271bba2d8e062c845a877225eefe117eef27b28a2c419a1ef860e19ff563c944b04998383b3c6551c075ee0844
-  data.tar.gz: 93b858d71f6f32324648d1fcd85604b373bc8f4a69601a445891eb81330b41413afdda8dc5c08526bd45bd1c7601f17ef9b1e93dc50ceb4ed67c05ba69b83921
+  metadata.gz: 2da58e993a59e4019e83f9885826672158bf7483b7310ef07f86b54d93ceb3675bf7509c656a976372debac167aa2c12d6e12214d71be0acff253e0dd3d682b5
+  data.tar.gz: 80ce1e443cc6eafaf9eb1746f3d617fcf4b33bae7621d28e1f36a2a00a1f57a2e2638a2a629e02b0bdda049208b458a72e3bf43b4098d054e17f41ff8351d9de

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
@@ -119,8 +136,8 @@ things to note.
 
 - The seeder will always be appended at the end of the array. If this is not the
 correct order, you'll need to adjust the array manually.
-- When adjusting the array, always keep the closing bracket on its own line, or
-the generator won't know where to put the new seeders.
+- The generator can append to either multiline or inline `%i[...]` seeders
+arrays.
 
 You can also tell the generator which seeding style to use.
 

data/lib/generators/planter/seeder_generator.rb

@@ -50,9 +50,7 @@ module Planter
 
         create_csv(seeder) if selected_seeding_method == :csv
 
-        inject_into_file "config/initializers/planter.rb",
-          "    #{seeder}\n",
-          before: /^\s*\]\s*$/
+        register_seeder(seeder)
       end
 
       def seeder_contents
@@ -94,6 +92,110 @@ module Planter
         end.join
       end
 
+      def register_seeder(seeder)
+        contents = ::File.read(initializer_full_path)
+        ::File.write(initializer_full_path, add_seeder_to_initializer(contents, seeder))
+      end
+
+      def add_seeder_to_initializer(contents, seeder)
+        assignment = contents.match(seeders_assignment_pattern)
+        unless assignment
+          raise Thor::Error, "Could not find config.seeders = %i[...] in #{initializer_path}"
+        end
+
+        opening_bracket_index = assignment.end(0) - 1
+        closing_bracket_index = closing_bracket_index_for(contents, opening_bracket_index)
+        unless closing_bracket_index
+          raise Thor::Error,
+            "Could not find the closing bracket for config.seeders in #{initializer_path}"
+        end
+
+        insert_seeder(contents, seeder, assignment[1], opening_bracket_index, closing_bracket_index)
+      end
+
+      def insert_seeder(
+        contents,
+        seeder,
+        assignment_indent,
+        opening_bracket_index,
+        closing_bracket_index
+      )
+        body = contents[(opening_bracket_index + 1)...closing_bracket_index]
+        updated = contents.dup
+
+        if body.include?("\n")
+          insert_multiline_seeder(
+            updated,
+            contents,
+            seeder,
+            assignment_indent,
+            body,
+            closing_bracket_index
+          )
+        elsif body.strip.empty?
+          updated.insert(closing_bracket_index, seeder)
+        else
+          updated.insert(closing_bracket_index, " #{seeder}")
+        end
+
+        updated
+      end
+
+      def insert_multiline_seeder(
+        updated,
+        contents,
+        seeder,
+        assignment_indent,
+        body,
+        closing_bracket_index
+      )
+        closing_line_start = contents.rindex("\n", closing_bracket_index) + 1
+        closing_line_prefix = contents[closing_line_start...closing_bracket_index]
+
+        if closing_line_prefix.match?(/\A[ \t]*\z/)
+          updated.insert(closing_line_start, "#{seeder_indent(body, assignment_indent)}#{seeder}\n")
+        else
+          updated.insert(closing_bracket_index, " #{seeder}")
+        end
+      end
+
+      def seeder_indent(body, assignment_indent)
+        item_line = body.lines.find { |line| line.match?(/\S/) }
+        indent = item_line&.match(/\A[ \t]*/).to_s
+        indent.empty? ? "#{assignment_indent}  " : indent
+      end
+
+      def closing_bracket_index_for(contents, opening_bracket_index)
+        depth = 1
+        index = opening_bracket_index + 1
+
+        while index < contents.length
+          if contents[index] == "\\"
+            index += 2
+            next
+          elsif contents[index] == "["
+            depth += 1
+          elsif contents[index] == "]"
+            depth -= 1
+            return index if depth.zero?
+          end
+
+          index += 1
+        end
+      end
+
+      def seeders_assignment_pattern
+        /^([ \t]*)config\.seeders\s*=\s*%i\[/
+      end
+
+      def initializer_path
+        "config/initializers/planter.rb"
+      end
+
+      def initializer_full_path
+        ::File.join(destination_root, initializer_path)
+      end
+
       def selected_seeding_method
         return unless options["seeding_method"]
 

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 = 5
+    MINOR = 0
 
     ##
     # Patch version.
     #
     # @return [Integer]
-    PATCH = 0
+    PATCH = 1
 
     module_function
 

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.1
 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