rails-mmd 0.1.0

data/lib/rails_mmd/render_plan_builder.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+require 'rails_mmd/attribute_types'
+require 'rails_mmd/canonical_json'
+require 'rails_mmd/redactor'
+require 'rails_mmd/safe_token_assigner'
+
+module RailsMmd
+  # Projects normalized IR into renderer-only ER or class render plans.
+  # rubocop:disable-next Metrics/AbcSize, Metrics/ClassLength, Metrics/MethodLength, Metrics/ParameterLists, Naming/MethodParameterName, Style/MultilineBlockChain
+  class RenderPlanBuilder
+    DomainResult = Struct.new(:domain_id, :payload, :diagnostics, keyword_init: true)
+
+    ER_MARKERS = {
+      '0..1' => ['|o', 'o|'],
+      '1..1' => ['||', '||'],
+      '0..many' => ['}o', 'o{'],
+      '1..many' => ['}|', '|{']
+    }.freeze
+    CLASS_MULTIPLICITIES = {
+      '0..1' => '0..1',
+      '1..1' => '1',
+      '0..many' => '0..*',
+      '1..many' => '1..*'
+    }.freeze
+    ASSOCIATION_LABEL_SUFFIX = /[?!=]\z/
+
+    def initialize(safe_tokens: SafeTokenAssigner.new, redactor: Redactor.new)
+      @safe_tokens = safe_tokens
+      @redactor = redactor
+    end
+
+    def build(ir:, artifact_kind:, direction:, attributes: :keys, comments: [], available_diagnostic_ids: [])
+      token_sets, diagnostics = token_sets_for(ir, artifact_kind, comments)
+      payload = payload_for(
+        ir: ir,
+        artifact_kind: artifact_kind,
+        direction: direction,
+        attributes: attributes.to_sym,
+        comments: comments,
+        token_sets: token_sets,
+        available_diagnostic_ids: available_diagnostic_ids
+      )
+
+      DomainResult.new(domain_id: ir.fetch('domain_id'), payload: payload, diagnostics: diagnostics)
+    end
+
+    private
+
+    attr_reader :redactor, :safe_tokens
+
+    def payload_for(ir:, artifact_kind:, direction:, attributes:, comments:, token_sets:, available_diagnostic_ids:)
+      payload = {
+        'schema_version' => 1,
+        'artifact_kind' => artifact_kind,
+        'domain_id' => ir.fetch('domain_id'),
+        'direction' => direction,
+        'entities' => entities_payload(ir, attributes, token_sets),
+        'relationships' => relationships_payload(ir, token_sets),
+        'comments' => comments_payload(comments, token_sets),
+        'diagnostic_ids' => diagnostic_ids(ir, available_diagnostic_ids),
+        'digest_sha256' => nil
+      }
+      payload.merge('digest_sha256' => CanonicalJson.digest_sha256(payload))
+    end
+
+    def token_sets_for(ir, artifact_kind, comments)
+      token_sets = {}
+      diagnostics = []
+      token_subjects(ir, comments).each do |token_kind, subjects|
+        assignment = safe_tokens.assign(
+          subjects,
+          scope: { artifact_kind: artifact_kind, domain_id: ir.fetch('domain_id'), token_kind: token_kind }
+        )
+        token_sets[token_kind] = assignment.fetch(:tokens)
+        diagnostics.concat(assignment.fetch(:diagnostics))
+      end
+      [token_sets, diagnostics]
+    end
+
+    def token_subjects(ir, comments)
+      {
+        'entity' => ir.fetch('entities').map do |entity|
+          subject(entity.fetch('entity_id'), structured_mermaid_text(entity.fetch('ruby_constant'), :ruby_constant))
+        end,
+        'attribute' => ir.fetch('entities').flat_map { |entity| attribute_subjects(entity) },
+        'relationship' => ir.fetch('relationships').map do |relationship|
+          subject(relationship.fetch('relationship_id'),
+                  relationship_label(relationship))
+        end,
+        'comment' => comments.map { |comment| subject(comment.fetch('comment_id'), comment.fetch('comment_id')) }
+      }
+    end
+
+    def subject(identity, source)
+      { identity: identity, source: source }
+    end
+
+    def attribute_subjects(entity)
+      entity.fetch('attributes').map do |attribute|
+        subject(attribute.fetch('attribute_id'), structured_mermaid_text(attribute.fetch('name'), :snake_identifier))
+      end
+    end
+
+    def entities_payload(ir, attributes, token_sets)
+      ir.fetch('entities').map do |entity|
+        {
+          'entity_id' => entity.fetch('entity_id'),
+          'safe_token' => token_sets.fetch('entity').fetch(entity.fetch('entity_id')),
+          'label' => structured_mermaid_text(entity.fetch('ruby_constant').split('::').last, :ruby_constant_label),
+          'attributes' => attributes == :none ? [] : attributes_payload(entity, token_sets)
+        }
+      end.sort_by { |entity| entity.fetch('entity_id') }
+    end
+
+    def attributes_payload(entity, token_sets)
+      entity.fetch('attributes').map do |attribute|
+        {
+          'attribute_id' => attribute.fetch('attribute_id'),
+          'safe_token' => token_sets.fetch('attribute').fetch(attribute.fetch('attribute_id')),
+          'label' => sanitize_attribute_name(attribute.fetch('name')),
+          'type' => AttributeTypes.normalize(attribute['type']),
+          'key_marker' => key_marker(attribute.fetch('role'))
+        }
+      end.sort_by { |attribute| [attribute.fetch('key_marker') == 'PK' ? 0 : 1, attribute.fetch('attribute_id')] }
+    end
+
+    def relationships_payload(ir, token_sets)
+      ir.fetch('relationships').map do |relationship|
+        relationship_payload(relationship, token_sets)
+      end.sort_by { |relationship| relationship.fetch('relationship_id') }
+    end
+
+    def relationship_payload(relationship, token_sets)
+      er_left, = ER_MARKERS.fetch(relationship.fetch('owner_cardinality'))
+      _, er_right = ER_MARKERS.fetch(relationship.fetch('target_cardinality'))
+      {
+        'relationship_id' => relationship.fetch('relationship_id'),
+        'safe_token' => token_sets.fetch('relationship').fetch(relationship.fetch('relationship_id')),
+        'owner_safe_token' => token_sets.fetch('entity').fetch(relationship.fetch('owner_entity_id')),
+        'target_safe_token' => token_sets.fetch('entity').fetch(relationship.fetch('target_entity_id')),
+        'label' => relationship_label(relationship),
+        'owner_cardinality' => relationship.fetch('owner_cardinality'),
+        'target_cardinality' => relationship.fetch('target_cardinality'),
+        'er_left_marker' => er_left,
+        'er_right_marker' => er_right,
+        'class_owner_multiplicity' => CLASS_MULTIPLICITIES.fetch(relationship.fetch('owner_cardinality')),
+        'class_target_multiplicity' => CLASS_MULTIPLICITIES.fetch(relationship.fetch('target_cardinality'))
+      }
+    end
+
+    def comments_payload(comments, token_sets)
+      comments.map do |comment|
+        {
+          'comment_id' => comment.fetch('comment_id'),
+          'safe_token' => token_sets.fetch('comment').fetch(comment.fetch('comment_id')),
+          'text' => sanitize_comment(comment.fetch('text'))
+        }
+      end.sort_by { |comment| comment.fetch('comment_id') }
+    end
+
+    def sanitize_comment(text)
+      free_text_mermaid_text(text)
+    end
+
+    def sanitize_attribute_name(name)
+      structured_mermaid_text(name, :snake_identifier)
+    end
+
+    def relationship_label(relationship)
+      structured_mermaid_text(relationship.fetch('association_name').to_s.sub(ASSOCIATION_LABEL_SUFFIX, ''),
+                              :snake_identifier)
+    end
+
+    def free_text_mermaid_text(value)
+      Redactor.sanitize_mermaid_free_text(value, sanitizer: redactor)
+    end
+
+    def structured_mermaid_text(value, grammar)
+      Redactor.sanitize_mermaid_structured(value, grammar: grammar)
+    end
+
+    def diagnostic_ids(ir, available_diagnostic_ids)
+      allowed = available_diagnostic_ids.map(&:to_s)
+      ir.fetch('diagnostic_ids').select { |diagnostic_id| allowed.include?(diagnostic_id) }.sort
+    end
+
+    def key_marker(role)
+      { 'primary_key' => 'PK', 'foreign_key' => 'FK' }.fetch(role)
+    end
+  end
+end

data/lib/rails_mmd/safe_token_assigner.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require 'rails_mmd/canonical_json'
+require 'rails_mmd/diagnostic_factory'
+
+module RailsMmd
+  # Mermaid-safe token generation and scoped collision resolution.
+  # @api private
+  class SafeTokenAssigner
+    TOKEN_KINDS = %w[entity attribute relationship diagnostic comment].freeze
+    ARTIFACT_KINDS = %w[er class].freeze
+
+    def initialize(diagnostics: DiagnosticFactory.new)
+      @diagnostic_factory = diagnostics
+    end
+
+    def assign(subjects, scope:)
+      validate_scope!(scope)
+      subjects_by_base_token = subjects.group_by { |subject| base_token(subject.fetch(:source)) }
+      tokens_by_identity = subjects_by_base_token.filter_map do |base_token, subjects_for_token|
+        [subjects_for_token.first.fetch(:identity), base_token] if subjects_for_token.one?
+      end.to_h
+      collision_diagnostics = assign_token_groups(subjects_by_base_token, scope, tokens_by_identity)
+
+      { tokens: tokens_by_identity, diagnostics: collision_diagnostics }
+    end
+
+    private
+
+    attr_reader :diagnostic_factory
+
+    def base_token(source)
+      token = source.to_s.unicode_normalize(:nfkd)
+      token = token.gsub('::', '_')
+      token = token.gsub(/([a-z\d])([A-Z])/, '\\1_\\2')
+      token = token.gsub(/([A-Z]+)([A-Z][a-z])/, '\\1_\\2')
+      token = token.gsub(/[^A-Za-z0-9]+/, '_')
+      token = token.delete('^A-Za-z0-9_')
+      token = token.squeeze('_').gsub(/\A_+|_+\z/, '').upcase
+      token = 'X' if token.empty?
+      token.match?(/\A\d/) ? "X_#{token}" : token
+    end
+
+    def validate_scope!(scope)
+      raise ArgumentError, 'invalid artifact_kind' unless ARTIFACT_KINDS.include?(scope.fetch(:artifact_kind))
+      raise ArgumentError, 'invalid token_kind' unless TOKEN_KINDS.include?(scope.fetch(:token_kind))
+    end
+
+    def assign_token_groups(subjects_by_base_token, scope, tokens_by_identity)
+      subjects_by_base_token.filter_map do |base_token, colliding_subjects|
+        next if colliding_subjects.one?
+
+        resolved_candidates = unique_collision_candidates(scope, base_token, colliding_subjects,
+                                                          tokens_by_identity.values)
+        collision_resolved = !resolved_candidates.nil?
+        tokens_by_identity.merge!(resolved_candidates) if collision_resolved
+        collision_diagnostic(scope, base_token, colliding_subjects, resolved: collision_resolved)
+      end
+    end
+
+    def unique_collision_candidates(scope, base_token, colliding_subjects, reserved_tokens)
+      suffix_length = 12
+      loop do
+        candidates = collision_candidates(scope, base_token, colliding_subjects, suffix_length)
+        return candidates if unique_candidates?(candidates, reserved_tokens)
+
+        suffix_length += 4
+        break if suffix_length > 64
+      end
+
+      nil
+    end
+
+    def unique_candidates?(candidates, reserved_tokens)
+      candidates.values.uniq.length == candidates.length && !candidates.values.intersect?(reserved_tokens)
+    end
+
+    def collision_candidates(scope, base_token, colliding_subjects, suffix_length)
+      colliding_subjects.to_h do |subject|
+        [
+          subject.fetch(:identity),
+          "#{base_token}_H#{collision_digest(scope, base_token, subject)[0, suffix_length]}"
+        ]
+      end
+    end
+
+    def collision_digest(scope, base_token, subject)
+      payload = {
+        'scope' => {
+          'artifact_kind' => scope.fetch(:artifact_kind),
+          'domain_id' => scope.fetch(:domain_id),
+          'token_kind' => scope.fetch(:token_kind)
+        },
+        'subject_identity' => subject.fetch(:identity),
+        'base_safe_token' => base_token
+      }
+      CanonicalJson.digest_sha256(payload).upcase
+    end
+
+    def collision_diagnostic(scope, base_token, colliding_subjects, resolved:)
+      diagnostic_factory.build(
+        code: 'SAFE_TOKEN_COLLISION',
+        subject_id: collision_subject_id(scope, base_token),
+        message: collision_message(base_token, resolved),
+        severity: resolved ? 'warning' : 'fatal',
+        metadata: collision_metadata(scope, base_token, colliding_subjects, resolved: resolved)
+      )
+    end
+
+    def collision_subject_id(scope, base_token)
+      "#{scope.fetch(:artifact_kind)}:#{scope.fetch(:domain_id)}:#{scope.fetch(:token_kind)}:#{base_token}"
+    end
+
+    def collision_metadata(scope, base_token, colliding_subjects, resolved:)
+      {
+        artifact_kind: scope.fetch(:artifact_kind),
+        domain_id: scope.fetch(:domain_id),
+        token_kind: scope.fetch(:token_kind),
+        base_safe_token: base_token,
+        collision_subject_count: colliding_subjects.length,
+        resolved: resolved
+      }
+    end
+
+    def collision_message(base_token, resolved)
+      state = resolved ? 'resolved' : 'unresolved'
+      "Safe-token collision #{state} for #{base_token}"
+    end
+  end
+end

data/lib/rails_mmd/schema_probe.rb

@@ -0,0 +1,376 @@
+# frozen_string_literal: true
+
+require 'rails_mmd/constant_resolver'
+require 'rails_mmd/diagnostic_factory'
+require 'rails_mmd/redactor'
+
+module RailsMmd
+  # Reads selected-domain-only schema metadata for resolved renderable records.
+  # rubocop:disable-next Metrics/ClassLength, Metrics/MethodLength
+  class SchemaProbe
+    DomainResult = Struct.new(:domain_id, :entities, :join_tables, :diagnostics, keyword_init: true)
+    Entity = Struct.new(
+      :ruby_constant,
+      :table_name,
+      :connection_context_id,
+      :columns,
+      :primary_key,
+      :foreign_keys,
+      :indexes,
+      keyword_init: true
+    )
+    Column = Struct.new(:name, :type, :nullable, keyword_init: true)
+    JoinTable = Struct.new(:table_name, :columns, :primary_key, keyword_init: true)
+    ForeignKey = Struct.new(:from_table, :column, :to_table, :primary_key, keyword_init: true)
+    Index = Struct.new(:columns, :unique, :where, :using, :expression, keyword_init: true)
+    # Carries valid metadata records when only some optional adapter rows degrade.
+    class PartialMetadataDegraded < StandardError
+      attr_reader :records
+
+      def initialize(records:, message:)
+        @records = records
+        super(message)
+      end
+    end
+    Result = Struct.new(:domains, :diagnostics, keyword_init: true)
+
+    def initialize(constant_resolver:, diagnostics: DiagnosticFactory.new, redactor: Redactor.new)
+      @constant_resolver = ConstantResolver.wrap(constant_resolver)
+      @diagnostic_factory = diagnostics
+      @redactor = redactor
+    end
+
+    def probe(domains:)
+      domain_results = domains.map { |domain| probe_domain(domain) }
+      all_diagnostics = domain_results.flat_map(&:diagnostics)
+
+      Result.new(domains: domain_results, diagnostics: all_diagnostics)
+    end
+
+    private
+
+    attr_reader :constant_resolver, :diagnostic_factory, :redactor
+
+    def probe_domain(domain)
+      connection_diagnostic = multi_db_diagnostic(domain)
+      return domain_result(domain, [], [connection_diagnostic]) if connection_diagnostic
+
+      entities = []
+      entity_models = []
+      output_diagnostics = []
+      domain.records.each do |record|
+        model = model_for(record)
+        entity, record_diagnostics = probe_record(domain.domain_id, record, model)
+        if entity
+          entities << entity
+          entity_models << model
+        end
+        output_diagnostics.concat(record_diagnostics)
+      end
+
+      domain_result(domain, entities, output_diagnostics, probe_join_tables(entity_models))
+    end
+
+    def domain_result(domain, entities, output_diagnostics, join_tables = [])
+      DomainResult.new(
+        domain_id: domain.domain_id, entities: entities,
+        join_tables: join_tables, diagnostics: output_diagnostics
+      )
+    end
+
+    def multi_db_diagnostic(domain)
+      raw_context_ids = domain.records.map(&:connection_context_id)
+      return if raw_context_ids.uniq.length < 2
+
+      connection_context_ids = raw_context_ids.map { |context_id| redactor.sanitize(context_id) }.sort
+
+      diagnostic_factory.build(
+        code: 'MULTI_DB_UNSUPPORTED',
+        message: "Domain #{domain.domain_id} selects multiple connection contexts",
+        subject_id: domain.domain_id,
+        metadata: { domain_id: domain.domain_id, connection_context_ids: connection_context_ids }
+      )
+    end
+
+    def probe_record(domain_id, record, model)
+      return probe_record_failure(domain_id, record, :table) if model.nil?
+
+      return probe_record_failure(domain_id, record, :table) unless table_exists?(model)
+
+      columns = read_columns(model)
+      primary_key = read_primary_key(model)
+      return probe_record_failure(domain_id, record, :table) if columns.nil?
+      return probe_record_failure(domain_id, record, :primary_key) unless scalar_primary_key?(primary_key)
+
+      build_entity(domain_id, record, model, columns, primary_key)
+    end
+
+    def model_for(record)
+      constant_resolver.resolve(record.ruby_constant)
+    end
+
+    def probe_record_failure(domain_id, record, failure_kind)
+      diagnostic = if failure_kind == :primary_key
+                     primary_key_unsupported(domain_id, record)
+                   else
+                     table_metadata_unavailable(domain_id, record, 'table metadata unavailable')
+                   end
+      [nil, [diagnostic]]
+    end
+
+    def build_entity(domain_id, record, model, columns, primary_key)
+      foreign_keys, foreign_key_diagnostic = degradable_metadata(domain_id, record, 'foreign_key') do
+        read_foreign_keys(model, record.table_name)
+      end
+      indexes, index_diagnostic = degradable_metadata(domain_id, record, 'unique_index') do
+        read_indexes(model, record.table_name)
+      end
+
+      [
+        Entity.new(
+          ruby_constant: record.ruby_constant,
+          table_name: record.table_name,
+          connection_context_id: record.connection_context_id,
+          columns: columns,
+          primary_key: primary_key,
+          foreign_keys: foreign_keys,
+          indexes: indexes
+        ),
+        [foreign_key_diagnostic, index_diagnostic].compact
+      ]
+    end
+
+    def table_exists?(model)
+      return true unless model.respond_to?(:table_exists?)
+
+      model.table_exists?
+    rescue LoadError, SyntaxError, StandardError
+      false
+    end
+
+    def read_columns(model)
+      return [] unless model.respond_to?(:columns)
+
+      model.columns.map { |column| column_record(column) }
+    rescue LoadError, SyntaxError, StandardError
+      nil
+    end
+
+    def probe_join_tables(models)
+      join_table_requests(models).group_by(&:last).filter_map do |table_name, requests|
+        requests.lazy.filter_map { |model, _name| read_join_table(model, table_name) }.first
+      end.sort_by(&:table_name)
+    end
+
+    def join_table_requests(models)
+      models.flat_map do |model|
+        habtm_reflections(model).filter_map do |reflection|
+          table_name = safe_value_from(reflection, :join_table)
+          [model, table_name] if table_name.is_a?(String) && !table_name.empty?
+        end
+      end
+    end
+
+    def join_table_connection(model, table_name)
+      return unless model.respond_to?(:connection)
+
+      connection = model.connection
+      return unless connection.respond_to?(:data_source_exists?) && connection.data_source_exists?(table_name)
+      return unless connection.respond_to?(:columns) && connection.respond_to?(:primary_key)
+
+      connection
+    rescue LoadError, SyntaxError, StandardError
+      nil
+    end
+
+    def habtm_reflections(model)
+      return [] unless model.respond_to?(:reflect_on_all_associations)
+
+      Array(model.reflect_on_all_associations(:has_and_belongs_to_many))
+    rescue LoadError, SyntaxError, StandardError
+      []
+    end
+
+    def read_join_table(model, table_name)
+      connection = join_table_connection(model, table_name)
+      return unless connection
+
+      JoinTable.new(
+        table_name: table_name,
+        columns: Array(connection.columns(table_name)).map { |column| column_record(column) },
+        primary_key: connection.primary_key(table_name)
+      )
+    rescue LoadError, SyntaxError, StandardError
+      nil
+    end
+
+    def column_record(column)
+      Column.new(
+        name: value_from(column, :name),
+        type: value_from(column, :type),
+        nullable: value_from(column, :null)
+      )
+    end
+
+    def safe_value_from(object, method_name)
+      value_from(object, method_name)
+    rescue LoadError, SyntaxError, StandardError
+      nil
+    end
+
+    def read_primary_key(model)
+      model.respond_to?(:primary_key) ? model.primary_key : nil
+    rescue LoadError, SyntaxError, StandardError
+      nil
+    end
+
+    def scalar_primary_key?(primary_key)
+      primary_key.is_a?(String) && !primary_key.empty?
+    end
+
+    def degradable_metadata(domain_id, record, metadata_kind)
+      [yield, nil]
+    rescue PartialMetadataDegraded => e
+      [e.records, metadata_degraded(domain_id, record, metadata_kind, e.message)]
+    rescue LoadError, NotImplementedError, SyntaxError, StandardError => e
+      [[], metadata_degraded(domain_id, record, metadata_kind, e.message)]
+    end
+
+    def read_foreign_keys(model, table_name)
+      foreign_keys = if model.respond_to?(:foreign_keys)
+                       model.foreign_keys
+                     else
+                       connection_metadata(model, :foreign_keys, table_name)
+                     end
+      valid_records = valid_metadata_records(Array(foreign_keys)) { |foreign_key| foreign_key_record(foreign_key) }
+      return valid_records if valid_records.length == Array(foreign_keys).length
+
+      raise PartialMetadataDegraded.new(records: valid_records, message: 'foreign_key metadata inconsistent')
+    end
+
+    def read_indexes(model, table_name)
+      indexes = if model.respond_to?(:indexes)
+                  model.indexes
+                else
+                  connection_metadata(model, :indexes, table_name)
+                end
+      column_names = model.columns.map { |column| value_from(column, :name) }
+      valid_records = valid_metadata_records(Array(indexes)) { |index| index_record(index, column_names) }
+      return valid_records if valid_records.length == Array(indexes).length
+
+      raise PartialMetadataDegraded.new(records: valid_records, message: 'unique_index metadata inconsistent')
+    end
+
+    def valid_metadata_records(records)
+      records.filter_map do |record|
+        yield record
+      rescue ArgumentError
+        nil
+      end
+    end
+
+    def foreign_key_record(foreign_key)
+      record = ForeignKey.new(
+        from_table: value_from(foreign_key, :from_table),
+        column: value_from(foreign_key, :column),
+        to_table: value_from(foreign_key, :to_table),
+        primary_key: value_from(foreign_key, :primary_key)
+      )
+      return record if [record.from_table, record.column, record.to_table, record.primary_key].all? do |value|
+        value.is_a?(String) && !value.empty?
+      end
+
+      raise ArgumentError, 'foreign_key metadata inconsistent'
+    end
+
+    def index_record(index, column_names)
+      record = Index.new(
+        columns: value_from(index, :columns),
+        unique: value_from(index, :unique),
+        where: value_from(index, :where),
+        using: normalized_index_using(value_from(index, :using)),
+        expression: value_from(index, :expression)
+      )
+      return record if index_record_valid?(record, column_names)
+
+      raise ArgumentError, 'unique_index metadata inconsistent'
+    end
+
+    def index_record_valid?(record, column_names)
+      index_columns_valid?(record.columns, column_names) &&
+        boolean?(record.unique) &&
+        optional_index_fields_valid?(record)
+    end
+
+    def index_columns_valid?(columns, column_names)
+      columns.is_a?(Array) &&
+        columns.all? { |column| column.is_a?(String) && !column.empty? } &&
+        columns.all? { |column| column_names.include?(column) }
+    end
+
+    def boolean?(value)
+      [true, false].include?(value)
+    end
+
+    def optional_index_fields_valid?(record)
+      optional_string_or_nil?(record.where) &&
+        optional_string_or_nil?(record.expression) &&
+        optional_string_or_nil?(record.using)
+    end
+
+    def optional_string_or_nil?(value)
+      value.nil? || value.is_a?(String)
+    end
+
+    def normalized_index_using(value)
+      return value.to_s if value.is_a?(Symbol)
+
+      value
+    end
+
+    def connection_metadata(model, method_name, table_name)
+      raise "#{method_name} metadata unavailable" unless model.respond_to?(:connection)
+      raise "#{method_name} metadata unavailable" unless model.connection.respond_to?(method_name)
+
+      model.connection.public_send(method_name, table_name)
+    end
+
+    def value_from(object, method_name)
+      return unless object.respond_to?(method_name)
+
+      object.public_send(method_name)
+    end
+
+    def table_metadata_unavailable(domain_id, record, reason)
+      diagnostic_factory.build(
+        code: 'MODEL_TABLE_MISSING',
+        message: "#{record.ruby_constant} table metadata is unavailable: #{reason}",
+        subject_id: "#{domain_id}:#{record.ruby_constant}",
+        metadata: { domain_id: domain_id, ruby_constant: record.ruby_constant, table_name: record.table_name }
+      )
+    end
+
+    def primary_key_unsupported(domain_id, record)
+      diagnostic_factory.build(
+        code: 'MODEL_PRIMARY_KEY_UNSUPPORTED',
+        message: "#{record.ruby_constant} primary key is unsupported",
+        subject_id: "#{domain_id}:#{record.ruby_constant}",
+        metadata: { domain_id: domain_id, ruby_constant: record.ruby_constant, table_name: record.table_name }
+      )
+    end
+
+    def metadata_degraded(domain_id, record, metadata_kind, reason)
+      diagnostic_factory.build(
+        code: 'DB_METADATA_DEGRADED',
+        message: "#{record.ruby_constant} #{metadata_kind} metadata is degraded",
+        subject_id: domain_id,
+        metadata: {
+          domain_id: domain_id,
+          ruby_constant: record.ruby_constant,
+          metadata_kind: metadata_kind,
+          reason: reason
+        }
+      )
+    end
+  end
+end