bulkrax 9.3.5 → 9.4.0

data/app/parsers/bulkrax/csv_parser.rb

@@ -4,7 +4,10 @@ module Bulkrax
   class CsvParser < ApplicationParser # rubocop:disable Metrics/ClassLength
     include ErroredEntries
     include ExportBehavior
+    include CsvParser::CsvTemplateGeneration
+    include CsvParser::CsvValidation
     attr_writer :collections, :file_sets, :works
+    attr_accessor :validation_mode
 
     def self.export_supported?
       true
@@ -14,12 +17,14 @@ module Bulkrax
       return @records if @records.present?
 
       file_for_import = only_updates ? parser_fields['partial_import_file_path'] : import_file_path
-      # data for entry does not need source_identifier for csv, because csvs are read sequentially and mapped after raw data is read.
       csv_data = entry_class.read_data(file_for_import)
-      importer.parser_fields['total'] = csv_data.count
-      importer.save
+      unless validation_mode
+        importer.parser_fields['total'] = csv_data.count
+        importer.save
+      end
 
       @records = csv_data.map { |record_data| entry_class.data_for_entry(record_data, nil, self) }
+      @records
     end
 
     # rubocop:disable Metrics/AbcSize
@@ -95,11 +100,11 @@ module Bulkrax
     def missing_elements(record)
       keys_from_record = keys_without_numbers(record.reject { |_, v| v.blank? }.keys.compact.uniq.map(&:to_s))
       keys = []
-      # Because we're persisting the mapping in the database, these are likely string keys.
-      # However, there's no guarantee.  So, we need to ensure that by running stringify.
-      importerexporter.mapping.stringify_keys.map do |k, v|
-        Array.wrap(v['from']).each do |vf|
-          keys << k if keys_from_record.include?(vf)
+      mapping_values = importerexporter.mapping.stringify_keys
+      mapping_values.each do |k, v|
+        from_values = Array.wrap(v.is_a?(Hash) ? (v['from'] || v[:from]) : nil)
+        from_values.each do |vf|
+          keys << k if vf.present? && keys_from_record.include?(vf.to_s.strip)
         end
       end
       required_elements.map(&:to_s) - keys.uniq.map(&:to_s)
@@ -360,8 +365,11 @@ module Bulkrax
                         else
                           Bulkrax.multi_value_element_split_on
                         end
+        files_dir = path_to_files
+        raise StandardError, "Record references local files but no files directory could be resolved from the import path" if files_dir.nil?
+
         r[file_mapping].split(split_pattern).map do |f|
-          file = File.join(path_to_files, f.tr(' ', '_'))
+          file = File.join(files_dir, f.strip.tr(' ', '_'))
           if File.exist?(file) # rubocop:disable Style/GuardClause
             file
           else
@@ -376,8 +384,11 @@ module Bulkrax
       filename = args.fetch(:filename, '')
 
       return @path_to_files if @path_to_files.present? && filename.blank?
+      # The zip file could be either the main import file, or a separate attachments zip file.
+      # We want to check for both of those before we determine the path to the files.
+      have_zip_file = zip? || (parser_fields['attachments_zip_path'] && zip_file?(parser_fields['attachments_zip_path']))
       @path_to_files = File.join(
-          zip? ? importer_unzip_path : File.dirname(import_file_path), 'files', filename
+          have_zip_file ? importer_unzip_path : File.dirname(import_file_path), 'files', filename
         )
 
       return @path_to_files if File.exist?(@path_to_files)
@@ -386,8 +397,29 @@ module Bulkrax
       File.join(importer_unzip_path, 'files', filename) if file? && zip?
     end
 
+    def unzip(file_to_unzip)
+      super
+      normalize_unzipped_files_structure(importer_unzip_path)
+    end
+
     private
 
+    # Ensure files extracted from a zip always land in a `files/` subdirectory
+    # regardless of how the zip was structured. If files were extracted directly
+    # into dest_dir (flat zip with no `files/` folder), move them into
+    # dest_dir/files/ so that path_to_files can reliably locate them.
+    def normalize_unzipped_files_structure(dest_dir)
+      flat_files = Dir.glob(File.join(dest_dir, '*')).select { |f| File.file?(f) && !f.end_with?('.csv') }
+      return if flat_files.empty?
+
+      files_dir = File.join(dest_dir, 'files')
+      FileUtils.mkdir_p(files_dir)
+      flat_files.each do |f|
+        dest = File.join(files_dir, File.basename(f))
+        FileUtils.mv(f, dest) unless File.exist?(dest)
+      end
+    end
+
     def unique_collection_identifier(collection_hash)
       entry_uid = collection_hash[source_identifier]
       entry_uid ||= if Bulkrax.fill_in_blank_source_identifiers.present?

data/app/parsers/concerns/bulkrax/csv_parser/csv_template_generation.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Bulkrax
+  class CsvParser < ApplicationParser
+    module CsvTemplateGeneration
+      extend ActiveSupport::Concern
+
+      class_methods do
+        # Generate a CSV template for the specified models.
+        #
+        # @param models [Array<String>, String] Model names or 'all' for all available models
+        # @param output [String] Output format: 'file' or 'csv_string'
+        # @param admin_set_id [String, nil] Optional admin set ID for context
+        # @param args [Hash] Additional arguments passed to output method (e.g., file_path)
+        # @return [String] File path (for 'file' output) or CSV string (for 'csv_string' output)
+        def generate_template(models: [], output: 'file', admin_set_id: nil, **args)
+          raise NameError, "Hyrax is not defined" unless defined?(::Hyrax)
+          TemplateContext.new(models: models, admin_set_id: admin_set_id).send("to_#{output}", **args)
+        end
+      end
+
+      ##
+      # Holds state for a single template generation run.
+      # Provides the interface expected by CsvTemplate:: components.
+      class TemplateContext
+        attr_reader :mappings, :all_models, :admin_set_id, :field_analyzer, :mapping_manager
+
+        def initialize(models: nil, admin_set_id: nil)
+          @admin_set_id = admin_set_id
+          @mapping_manager = CsvTemplate::MappingManager.new
+          @mappings = @mapping_manager.mappings
+          @field_analyzer = CsvTemplate::FieldAnalyzer.new(@mappings, admin_set_id)
+          @all_models = CsvTemplate::ModelLoader.new(Array.wrap(models)).models
+          @csv_builder = CsvTemplate::CsvBuilder.new(self)
+        end
+
+        def to_file(file_path: nil)
+          file_path ||= CsvTemplate::FilePathGenerator.default_path(@admin_set_id)
+          @csv_builder.write_to_file(file_path)
+          file_path
+        end
+
+        def to_csv_string
+          @csv_builder.generate_string
+        end
+
+        def field_metadata_for_all_models
+          @field_metadata ||= @all_models.each_with_object({}) do |model, hash|
+            field_list = @field_analyzer.find_or_create_field_list_for(model_name: model)
+            hash[model] = {
+              properties: field_list.dig(model, "properties") || [],
+              required_terms: field_list.dig(model, "required_terms") || [],
+              controlled_vocab_terms: field_list.dig(model, "controlled_vocab_terms") || []
+            }
+          end
+        end
+
+        def valid_headers_for_models
+          @valid_headers ||= begin
+            column_builder = CsvTemplate::ColumnBuilder.new(self)
+            all_columns = column_builder.all_columns
+            all_columns - CsvTemplate::CsvBuilder::IGNORED_PROPERTIES
+                             rescue StandardError => e
+                               Rails.logger.error("Error building valid headers: #{e.message}")
+                               standard_fields = %w[model source_identifier parent parents file]
+                               model_fields = field_metadata_for_all_models.values.flat_map { |m| m[:properties] }
+                               (standard_fields + model_fields).uniq
+          end
+        end
+      end
+    end
+  end
+end

data/app/parsers/concerns/bulkrax/csv_parser/csv_validation.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Bulkrax
+  class CsvParser < ApplicationParser
+    module CsvValidation
+      extend ActiveSupport::Concern
+
+      included do
+        # Lightweight struct used to satisfy the CsvTemplate::ColumnBuilder
+        # interface without constructing a full template context.
+        ValidationContext = Struct.new(:mapping_manager, :field_analyzer, :all_models, :mappings, keyword_init: true)
+      end
+
+      class_methods do
+        include CsvValidationHelpers
+
+        # Validate a CSV (and optional zip) without a persisted Importer record.
+        #
+        # @param csv_file [File, ActionDispatch::Http::UploadedFile, String] path or file object
+        # @param zip_file [File, ActionDispatch::Http::UploadedFile, nil]
+        # @param admin_set_id [String, nil]
+        # @return [Hash] validation result compatible with the guided import UI
+        def validate_csv(csv_file:, zip_file: nil, admin_set_id: nil)
+          raw_csv, headers, mapping_manager, mappings, source_id_key, csv_data, field_metadata, field_analyzer =
+            parse_csv_inputs(csv_file, admin_set_id)
+
+          all_ids          = csv_data.map { |r| r[:source_identifier] }.compact.to_set
+          header_issues    = check_headers(headers, raw_csv, mapping_manager, mappings, field_metadata, field_analyzer)
+          missing_required = header_issues[:missing_required]
+          notices, row_errors, file_validator, collections, works, file_sets =
+            run_validations(csv_data, all_ids, headers, source_id_key, mappings, field_metadata, missing_required, zip_file, admin_set_id)
+
+          result = assemble_result(
+            headers: headers, missing_required: missing_required, header_issues: header_issues,
+            row_errors: row_errors, csv_data: csv_data, file_validator: file_validator,
+            collections: collections, works: works, file_sets: file_sets, notices: notices
+          )
+          apply_rights_statement_validation_override!(result, missing_required)
+          result[:raw_csv_data] = csv_data
+          result
+        end
+
+        private
+
+        # Builds notices, runs row validators, file validator, and hierarchy extraction.
+        # Returns [notices, row_errors, file_validator, collections, works, file_sets].
+        def run_validations(csv_data, all_ids, headers, source_id_key, mappings, field_metadata, missing_required, zip_file, admin_set_id) # rubocop:disable Metrics/ParameterLists
+          find_record = build_find_record
+          notices     = []
+          append_missing_source_id!(missing_required, headers, source_id_key, csv_data.map { |r| r[:model] }.compact.uniq)
+          append_missing_model_notice!(notices, headers, csv_data)
+
+          row_errors                       = run_row_validators(csv_data, all_ids, source_id_key, mappings, field_metadata, find_record, notices)
+          file_validator                   = CsvTemplate::FileValidator.new(csv_data, zip_file, admin_set_id)
+          collections, works, file_sets    = extract_hierarchy_items(csv_data, all_ids, find_record, mappings)
+          [notices, row_errors, file_validator, collections, works, file_sets]
+        end
+
+        # Reads the CSV, resolves mappings, parses rows, and builds field metadata.
+        # Returns the values needed by all subsequent validation steps.
+        def parse_csv_inputs(csv_file, admin_set_id)
+          # Use CsvEntry.read_data so header normalisation is identical to a real import.
+          raw_csv = CsvEntry.read_data(csv_file)
+          headers = raw_csv.headers.map(&:to_s)
+
+          mapping_manager = CsvTemplate::MappingManager.new
+          mappings        = mapping_manager.mappings
+
+          source_id_key = resolve_validation_key(mapping_manager, flag: 'source_identifier', default: :source_identifier)
+          parent_key    = resolve_validation_key(mapping_manager, flag: 'related_parents_field_mapping',  default: :parents)
+          children_key  = resolve_validation_key(mapping_manager, flag: 'related_children_field_mapping', default: :children)
+          file_key      = resolve_validation_key(mapping_manager, key: 'file',                            default: :file)
+
+          csv_data       = parse_validation_rows(raw_csv, source_id_key, parent_key, children_key, file_key)
+          all_models     = csv_data.map { |r| r[:model] }.compact.uniq
+          all_models    |= [Bulkrax.default_work_type] if Bulkrax.default_work_type.present?
+          field_analyzer = CsvTemplate::FieldAnalyzer.new(mappings, admin_set_id)
+          field_metadata = build_validation_field_metadata(all_models, field_analyzer)
+
+          [raw_csv, headers, mapping_manager, mappings, source_id_key, csv_data, field_metadata, field_analyzer]
+        end
+
+        # Runs all header-level checks and returns a hash of results.
+        def check_headers(headers, raw_csv, mapping_manager, mappings, field_metadata, field_analyzer) # rubocop:disable Metrics/ParameterLists
+          all_models    = field_metadata.keys
+          valid_headers = build_valid_validation_headers(mapping_manager, field_analyzer,
+                                                         all_models, mappings, field_metadata)
+          suffixed      = headers.select { |h| h.match?(/_\d+\z/) }
+          valid_headers = (valid_headers + suffixed).uniq
+
+          {
+            missing_required: find_missing_required_headers(headers, field_metadata, mapping_manager),
+            unrecognized: find_unrecognized_validation_headers(headers, valid_headers),
+            empty_columns: find_empty_column_positions(headers, raw_csv)
+          }
+        end
+
+        def extract_hierarchy_items(csv_data, all_ids, find_record, mappings)
+          extract_validation_items(
+            csv_data, all_ids, find_record,
+            parent_split_pattern: resolve_parent_split_pattern(mappings),
+            child_split_pattern: resolve_children_split_pattern(mappings) || '|'
+          )
+        end
+
+        # Runs all registered row validators and returns the collected errors.
+        def run_row_validators(csv_data, all_ids, source_id_key, mappings, field_metadata, find_record, notices = []) # rubocop:disable Metrics/ParameterLists
+          context = {
+            errors: [],
+            warnings: [],
+            seen_ids: {},
+            all_ids: all_ids,
+            source_identifier: source_id_key.to_s,
+            parent_split_pattern: resolve_parent_split_pattern(mappings),
+            child_split_pattern: resolve_children_split_pattern(mappings),
+            parent_column: resolve_relationship_column(mappings, 'related_parents_field_mapping', 'parents'),
+            children_column: resolve_relationship_column(mappings, 'related_children_field_mapping', 'children'),
+            mappings: mappings,
+            field_metadata: field_metadata,
+            find_record_by_source_identifier: find_record,
+            relationship_graph: build_relationship_graph(csv_data, mappings),
+            notices: notices
+          }
+          csv_data.each_with_index do |record, index|
+            row_number = index + 2 # 1-indexed, plus header row
+            Bulkrax.csv_row_validators.each { |v| v.call(record, row_number, context) }
+          end
+          context[:errors]
+        end
+      end
+    end
+  end
+end

data/app/parsers/concerns/bulkrax/csv_parser/csv_validation_helpers.rb

@@ -0,0 +1,282 @@
+# frozen_string_literal: true
+
+module Bulkrax
+  class CsvParser < ApplicationParser
+    # Private helper methods for CsvValidation.
+    module CsvValidationHelpers # rubocop:disable Metrics/ModuleLength
+      include CsvValidationHierarchy
+
+      # Resolve a symbol key from mappings for use as a record hash key.
+      # Returns a Symbol matching the parser's symbol-keyed record hash.
+      def resolve_validation_key(mapping_manager, key: nil, flag: nil, default:)
+        options = mapping_manager.resolve_column_name(key: key, flag: flag, default: default.to_s)
+        options.first&.to_sym || default
+      end
+
+      # Parse rows from a CsvEntry.read_data result into the canonical record shape.
+      # CsvEntry.read_data returns CSV::Row objects with symbol headers; blank rows
+      # are already filtered by CsvWrapper.
+      def parse_validation_rows(raw_csv, source_id_key, parent_key, children_key, file_key)
+        raw_csv.map do |row|
+          # CSV::Row#to_h converts symbol headers → string-keyed hash
+          row_hash = row.to_h.transform_keys(&:to_s)
+          {
+            source_identifier: row[source_id_key],
+            model: row[:model],
+            parent: row[parent_key],
+            children: row[children_key],
+            file: row[file_key],
+            raw_row: row_hash
+          }
+        end
+      rescue StandardError => e
+        Rails.logger.error("CsvParser.validate_csv: error parsing rows – #{e.message}")
+        []
+      end
+
+      def build_validation_field_metadata(all_models, field_analyzer)
+        all_models.each_with_object({}) do |model, hash|
+          field_list = field_analyzer.find_or_create_field_list_for(model_name: model)
+          hash[model] = {
+            properties: field_list.dig(model, 'properties') || [],
+            required_terms: field_list.dig(model, 'required_terms') || [],
+            controlled_vocab_terms: field_list.dig(model, 'controlled_vocab_terms') || []
+          }
+        end
+      end
+
+      def build_valid_validation_headers(mapping_manager, field_analyzer, all_models, mappings, field_metadata)
+        svc = ValidationContext.new(
+          mapping_manager: mapping_manager,
+          field_analyzer: field_analyzer,
+          all_models: all_models,
+          mappings: mappings
+        )
+        all_cols = CsvTemplate::ColumnBuilder.new(svc).all_columns
+        all_cols - CsvTemplate::CsvBuilder::IGNORED_PROPERTIES
+      rescue StandardError => e
+        Rails.logger.error("CsvParser.validate_csv: error building valid headers – #{e.message}")
+        standard = %w[model source_identifier parents children file]
+        model_fields = field_metadata.values.flat_map { |m| m[:properties] }
+                                            .map { |prop| mapping_manager.key_to_mapped_column(prop) }
+        (standard + model_fields).uniq
+      end
+
+      def find_missing_required_headers(headers, field_metadata, mapping_manager)
+        csv_keys = headers.map { |h| mapping_manager.mapped_to_key(h).sub(/_\d+\z/, '') }.uniq
+        missing = []
+        field_metadata.each do |model, meta|
+          (meta[:required_terms] || []).each do |field|
+            missing << { model: model, field: field } unless csv_keys.include?(field)
+          end
+        end
+        missing.uniq
+      end
+
+      def find_unrecognized_validation_headers(headers, valid_headers)
+        checker = DidYouMean::SpellChecker.new(dictionary: valid_headers)
+        headers
+          .reject { |h| h.blank? || valid_headers.include?(h) || valid_headers.include?(h.sub(/_\d+\z/, '')) }
+          .index_with { |h| checker.correct(h).first }
+      end
+
+      def find_empty_column_positions(headers, raw_csv)
+        headers.each_with_index.filter_map do |h, i|
+          next if h.present?
+          has_data = raw_csv.any? { |row| row.fields[i].present? }
+          i + 1 if has_data
+        end
+      end
+
+      # Adds a missing source_identifier entry to missing_required when the column
+      # is absent and fill_in_blank_source_identifiers is not configured.
+      def append_missing_source_id!(missing_required, headers, source_id_key, all_models)
+        return if headers.map(&:to_s).include?(source_id_key.to_s)
+        return if Bulkrax.fill_in_blank_source_identifiers.present?
+
+        all_models.each { |model| missing_required << { model: model, field: source_id_key.to_s } }
+      end
+
+      # Adds a file-level notice when the model column is absent or every row has a blank
+      # model value, indicating that the default work type will be used for all rows.
+      # When this notice is present the per-row default_work_type_used warnings are
+      # suppressed in the formatter — no need to repeat the same message for every row.
+      def append_missing_model_notice!(notices, headers, csv_data)
+        default_model = Bulkrax.default_work_type
+        return if default_model.blank?
+
+        model_column_present = headers.map(&:to_s).include?('model')
+        all_rows_blank = model_column_present && csv_data.all? { |r| r[:model].blank? }
+
+        return if model_column_present && !all_rows_blank
+
+        key_suffix = all_rows_blank ? 'column_empty' : 'column_missing'
+        base_key   = 'bulkrax.importer.guided_import.validation.default_work_type_notice'
+        notices << {
+          field: 'model',
+          default_work_type: default_model,
+          message: I18n.t("#{base_key}.message_#{key_suffix}", default_work_type: default_model),
+          suggestion: I18n.t("#{base_key}.suggestion_#{key_suffix}")
+        }
+      end
+
+      def apply_rights_statement_validation_override!(result, missing_required)
+        only_rights = missing_required.present? &&
+                      missing_required.all? { |h| h[:field].to_s == 'rights_statement' }
+        return unless only_rights && !result[:isValid]
+        return if result[:headers].blank?
+        return if result[:missingFiles]&.any?
+
+        result[:isValid]     = true
+        result[:hasWarnings] = true
+      end
+
+      # Assembles the final result hash returned to the guided import UI.
+      def assemble_result(headers:, missing_required:, header_issues:, row_errors:, csv_data:, file_validator:, collections:, works:, file_sets:, notices: []) # rubocop:disable Metrics/ParameterLists
+        row_error_entries   = row_errors.select { |e| e[:severity] == 'error' }
+        row_warning_entries = row_errors.select { |e| e[:severity] == 'warning' }
+        has_errors   = missing_required.any? || headers.blank? || csv_data.empty? ||
+                       file_validator.missing_files.any? || row_error_entries.any?
+        has_warnings = header_issues[:unrecognized].any? || header_issues[:empty_columns].any? ||
+                       file_validator.possible_missing_files? || row_warning_entries.any? || notices.any?
+
+        {
+          headers: headers,
+          missingRequired: missing_required,
+          notices: notices,
+          unrecognized: header_issues[:unrecognized],
+          emptyColumns: header_issues[:empty_columns],
+          rowCount: csv_data.length,
+          isValid: !has_errors,
+          hasWarnings: has_warnings,
+          rowErrors: row_errors,
+          collections: collections,
+          works: works,
+          fileSets: file_sets,
+          totalItems: csv_data.length,
+          fileReferences: file_validator.count_references,
+          missingFiles: file_validator.missing_files,
+          foundFiles: file_validator.found_files_count,
+          zipIncluded: file_validator.zip_included?
+        }
+      end
+
+      # Builds the find_record lambda used by row validators and hierarchy extraction.
+      def build_find_record
+        all_mappings = Bulkrax.field_mappings['Bulkrax::CsvParser'] || {}
+        work_identifier = all_mappings.find { |_k, v| v['source_identifier'] == true }&.first || 'source'
+        work_identifier_search = Array.wrap(all_mappings.dig(work_identifier, 'search_field')).first&.to_s ||
+                                 "#{work_identifier}_sim"
+        ->(id) { find_record_by_source_identifier(id, work_identifier, work_identifier_search) }
+      end
+
+      # Attempt to locate an existing repository record by its identifier.
+      # The identifier may be a repository object ID or a source_identifier property value.
+      # Checks the repository directly (by ID, then by Solr property search) — a Bulkrax
+      # Entry record alone is not sufficient, as the object may never have been created.
+      #
+      # @param identifier [String]
+      # @param work_identifier [String] the source_identifier property name (e.g. "source")
+      # @param work_identifier_search [String] the Solr field for source_identifier (e.g. "source_sim")
+      # @return [Boolean] true if a matching repository object is found
+      def find_record_by_source_identifier(identifier, work_identifier, work_identifier_search)
+        return false if identifier.blank?
+
+        return true if Bulkrax.object_factory.find_or_nil(identifier).present?
+
+        [Bulkrax.collection_model_class, *Bulkrax.curation_concerns].any? do |klass|
+          Bulkrax.object_factory.search_by_property(
+            value: identifier,
+            klass: klass,
+            search_field: work_identifier_search,
+            name_field: work_identifier
+          ).present?
+        end
+      rescue StandardError
+        false
+      end
+
+      # Returns the raw CSV column name (String) for a relationship field.
+      # Looks for the mapping entry flagged with +flag+ and returns its first +from+ value,
+      # falling back to +default+ when none is found.
+      def resolve_relationship_column(mappings, flag, default)
+        entry = mappings.find { |_k, v| v.is_a?(Hash) && v[flag] }
+        entry&.last&.dig('from')&.first || default
+      end
+
+      def resolve_parent_split_pattern(mappings)
+        split_val = mappings.dig('parents', 'split') || mappings.dig(:parents, :split)
+        return nil if split_val.blank?
+        return Bulkrax::DEFAULT_MULTI_VALUE_ELEMENT_SPLIT_ON if split_val == true
+
+        split_val
+      end
+
+      def resolve_children_split_pattern(mappings)
+        split_val = mappings.dig('children', 'split') || mappings.dig(:children, :split)
+        return nil if split_val.blank?
+        return Bulkrax::DEFAULT_MULTI_VALUE_ELEMENT_SPLIT_ON if split_val == true
+
+        split_val
+      end
+
+      # Builds a graph of { source_identifier => [parent_ids] } from all CSV records.
+      # Used by CircularReference validator to detect cycles across the whole CSV.
+      #
+      # Parent edges are collected from both directions:
+      #   - explicit parent declarations (parents / parents_N columns)
+      #   - inverted child declarations (children / children_N columns), mirroring
+      #     the normalisation done in importers_stepper.js#normalizeRelationships
+      def build_relationship_graph(csv_data, mappings)
+        parent_column   = resolve_relationship_column(mappings, 'related_parents_field_mapping', 'parents')
+        children_column = resolve_relationship_column(mappings, 'related_children_field_mapping', 'children')
+        parent_suffix   = /\A#{Regexp.escape(parent_column)}_\d+\z/
+        children_suffix = /\A#{Regexp.escape(children_column)}_\d+\z/
+
+        graph = build_parent_edges(csv_data, parent_suffix, resolve_parent_split_pattern(mappings))
+        invert_child_edges(graph, csv_data, children_suffix, resolve_children_split_pattern(mappings))
+        graph
+      end
+
+      def build_parent_edges(csv_data, suffix_pattern, split_pattern)
+        csv_data.each_with_object({}) do |record, graph|
+          id = record[:source_identifier]
+          next if id.blank?
+
+          base_ids = split_or_single(record[:parent], split_pattern)
+          suffix_ids = suffixed_values(record[:raw_row], suffix_pattern)
+          graph[id] = (base_ids + suffix_ids).uniq
+        end
+      end
+
+      def invert_child_edges(graph, csv_data, suffix_pattern, split_pattern)
+        csv_data.each do |record|
+          id = record[:source_identifier]
+          next if id.blank?
+
+          child_ids = split_or_single(record[:children], split_pattern) +
+                      suffixed_values(record[:raw_row], suffix_pattern)
+          child_ids.each do |child_id|
+            graph[child_id] ||= []
+            graph[child_id] << id unless graph[child_id].include?(id)
+          end
+        end
+      end
+
+      def split_or_single(value, split_pattern)
+        if split_pattern
+          value.to_s.split(split_pattern).map(&:strip).reject(&:blank?)
+        elsif value.present?
+          [value.to_s.strip]
+        else
+          []
+        end
+      end
+
+      def suffixed_values(raw_row, suffix_pattern)
+        raw_row.select { |k, _| k.to_s.match?(suffix_pattern) }
+               .values.map(&:to_s).map(&:strip).reject(&:blank?)
+      end
+    end
+  end
+end