rails2qdbd 0.1.0

data/lib/rails2qdbd/literal.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Rails2qdbd
+  # Turns Prism nodes into plain Ruby values without evaluating anything: project code is never run.
+  module Literal
+    # Returned for anything that is not a literal (method calls, variables, constants, ...).
+    UNKNOWN = Object.new.tap { |o| def o.inspect = "Literal::UNKNOWN" }.freeze
+
+    module_function
+
+    def value(node)
+      case node
+      when Prism::StringNode, Prism::SymbolNode then node.unescaped
+      when Prism::IntegerNode, Prism::FloatNode then node.value
+      when Prism::TrueNode then true
+      when Prism::FalseNode then false
+      when Prism::NilNode then nil
+      when Prism::ArrayNode then all_known(node.elements.map { |element| value(element) })
+      when Prism::HashNode, Prism::KeywordHashNode then hash_value(node)
+      when Prism::LambdaNode then lambda_value(node)
+      when Prism::RegularExpressionNode then regexp(node)
+      else UNKNOWN
+      end
+    end
+
+    def known?(value) = !value.equal?(UNKNOWN)
+
+    # [positional nodes, { key_symbol => value node }] of a call's arguments.
+    def arguments(call)
+      nodes = call.arguments&.arguments || []
+      keywords = nodes.last if nodes.last.is_a?(Prism::KeywordHashNode)
+      nodes = nodes[0...-1] if keywords
+      options = {}
+      keywords&.elements&.each do |element|
+        next unless element.is_a?(Prism::AssocNode) && element.key.is_a?(Prism::SymbolNode)
+
+        options[element.key.unescaped.to_sym] = element.value
+      end
+      [nodes, options]
+    end
+
+    # Full constant name of a ConstantReadNode / ConstantPathNode ("ActiveRecord::Base"), else nil.
+    def constant_name(node)
+      case node
+      when Prism::ConstantReadNode then node.name.to_s
+      when Prism::ConstantPathNode
+        parent = node.parent ? constant_name(node.parent) : ""
+        parent && "#{parent}::#{node.name}".delete_prefix("::")
+      end
+    end
+
+    def hash_value(node)
+      node.elements.each_with_object({}) do |element, result|
+        return UNKNOWN unless element.is_a?(Prism::AssocNode)
+
+        key = value(element.key)
+        val = value(element.value)
+        return UNKNOWN unless known?(key) && known?(val)
+
+        result[key.is_a?(String) ? key.to_sym : key] = val
+      end
+    end
+
+    def regexp(node)
+      flags = (node.ignore_case? ? Regexp::IGNORECASE : 0) | (node.extended? ? Regexp::EXTENDED : 0) |
+              (node.multi_line? ? Regexp::MULTILINE : 0)
+      Regexp.new(node.unescaped, flags)
+    end
+
+    def all_known(values) = values.all? { |v| known?(v) } ? values : UNKNOWN
+
+    # Rails dumps SQL defaults as `-> { "now()" }`; the string is the expression.
+    def lambda_value(node)
+      statements = node.body&.body || []
+      statements.size == 1 && statements.first.is_a?(Prism::StringNode) ? statements.first.unescaped : UNKNOWN
+    end
+  end
+end

data/lib/rails2qdbd/model_scanner.rb

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Rails2qdbd
+  # Reads model files statically into Catalog::Models: associations,
+  # enums, attachments, table overrides, abstract classes, STI parents and concerns.
+  class ModelScanner
+    include Catalog
+
+    ASSOCIATIONS = %i[belongs_to has_one has_many has_and_belongs_to_many].freeze
+    ASSOCIATION_OPTIONS = %i[class_name foreign_key primary_key polymorphic as through join_table
+                           association_foreign_key foreign_type].freeze
+    ATTACHMENTS = { has_one_attached: :one, has_many_attached: :many }.freeze
+    ENUM_OPTIONS = %i[prefix suffix scopes default instance_methods validate].freeze
+    ROOTS = %w[ActiveRecord::Base].freeze
+    # Assumed abstract when the project has no file for it.
+    IMPLICIT_ABSTRACT = %w[ApplicationRecord].freeze
+
+    # One class or concern as written, before deciding whether it is a model.
+    Unit = Struct.new(:model, :scopes, :warnings, :concern, keyword_init: true)
+
+    attr_reader :diagnostics
+
+    def initialize
+      @diagnostics = []
+    end
+
+    # sources: { relative_path => source }. Returns { "Admin::User" => Model } for models only.
+    def scan(sources:)
+      @units = {}
+      sources.sort.each { |path, source| scan_file(path, source) }
+      models = @units.values.reject(&:concern).select { |unit| model?(unit.model.name) }
+      models.sort_by { |unit| unit.model.name }.to_h do |unit|
+        apply_concerns(unit)
+        # A concern's warnings arrive with every class that includes it; report them once.
+        @diagnostics.concat(unit.warnings.uniq - @diagnostics)
+        [unit.model.name, unit.model]
+      end
+    end
+
+    private
+
+    def scan_file(path, source)
+      @path = path
+      result = Prism.parse(source)
+      return @diagnostics << Diagnostic.new(message: "syntax error, file skipped", path: path) if result.failure?
+
+      visit_scope(result.value.statements.body, [])
+    end
+
+    # scopes: full names of the enclosing modules/classes, outermost first.
+    def visit_scope(statements, scopes)
+      statements.each do |node|
+        case node
+        when Prism::ModuleNode then visit_module(node, scopes)
+        when Prism::ClassNode then visit_class(node, scopes)
+        end
+      end
+    end
+
+    def visit_module(node, scopes)
+      name = qualified(Literal.constant_name(node.constant_path), scopes)
+      body = node.body&.body || []
+      included = body.find { |n| n.is_a?(Prism::CallNode) && n.name == :included && n.receiver.nil? && n.block }
+      if included || body.any? { |n| concern_extension?(n) }
+        unit = unit_for(name, scopes + [name], concern: true)
+        collect(included.block.body&.body || [], unit) if included
+        body.each { |n| add_include(n, unit) }
+      end
+      visit_scope(body, scopes + [name])
+    end
+
+    def visit_class(node, scopes)
+      name = qualified(Literal.constant_name(node.constant_path), scopes)
+      unit = unit_for(name, scopes + [name], concern: false)
+      unit.model.superclass ||= Literal.constant_name(node.superclass)
+      unit.model.path ||= @path
+      unit.model.line ||= node.location.start_line
+      collect(node.body&.body || [], unit)
+      visit_scope(node.body&.body || [], scopes + [name])
+    end
+
+    # `extend ActiveSupport::Concern`: the module's includes reach the class, even without `included do`.
+    def concern_extension?(node)
+      node.is_a?(Prism::CallNode) && node.name == :extend && node.receiver.nil? &&
+        node.arguments&.arguments&.any? { |arg| Literal.constant_name(arg) == "ActiveSupport::Concern" }
+    end
+
+    def unit_for(name, scopes, concern:)
+      @units[name] ||= Unit.new(model: Model.new(name: name), scopes: scopes, warnings: [], concern: concern)
+    end
+
+    def qualified(name, scopes) = scopes.empty? ? name : "#{scopes.last}::#{name}"
+
+    # Class-body declarations; `inherited` lets with_options pass its options down.
+    def collect(statements, unit, inherited = {})
+      statements.each do |node|
+        next unless node.is_a?(Prism::CallNode)
+
+        if node.receiver.is_a?(Prism::SelfNode) then self_assignment(node, unit.model)
+        elsif node.receiver.nil? || node.receiver.is_a?(Prism::LocalVariableReadNode)
+          declaration(node, unit, inherited)
+        end
+      end
+    end
+
+    def self_assignment(node, model)
+      value = Literal.value(node.arguments&.arguments&.first)
+      return unless Literal.known?(value)
+
+      case node.name
+      when :table_name= then model.table_name = value.to_s
+      when :primary_key= then model.primary_key = value.is_a?(Array) ? value.map(&:to_s) : value.to_s
+      when :abstract_class= then model.abstract = value == true
+      end
+    end
+
+    def declaration(node, unit, inherited)
+      case node.name
+      when *ASSOCIATIONS then association(node, unit, inherited)
+      when *ATTACHMENTS.keys then attachment(node, unit.model)
+      when :enum then enum(node, unit)
+      when :include then add_include(node, unit)
+      when :primary_abstract_class then unit.model.abstract = true
+      when :with_options then with_options(node, unit, inherited)
+      end
+    end
+
+    def association(node, unit, inherited)
+      args, options = Literal.arguments(node)
+      name = Literal.value(args.first)
+      return unless name.is_a?(Symbol) || name.is_a?(String)
+
+      values = inherited.dup
+      options.slice(*ASSOCIATION_OPTIONS).each do |key, value_node|
+        value = Literal.value(value_node)
+        unless Literal.known?(value)
+          return skip(unit, node, "#{unit.model.name} #{node.name} :#{name}: non-literal #{key}, skipped")
+        end
+
+        values[key] = value
+      end
+      values = values.transform_values { |v| v.is_a?(Symbol) ? v.to_s : v }
+      unit.model.associations << Association.new(macro: node.name, name: name.to_s, options: values,
+                                                 path: @path, line: node.location.start_line)
+    end
+
+    def with_options(node, unit, inherited)
+      return unless node.block
+
+      _, options = Literal.arguments(node)
+      values = options.slice(*ASSOCIATION_OPTIONS).transform_values { |v| Literal.value(v) }
+      return skip(unit, node, "#{unit.model.name} with_options: non-literal options, skipped") unless values.values.all? { |v| Literal.known?(v) }
+
+      collect(node.block.body&.body || [], unit, inherited.merge(values))
+    end
+
+    def attachment(node, model)
+      name = Literal.value(node.arguments&.arguments&.first)
+      model.attachments << [name.to_s, ATTACHMENTS.fetch(node.name)] if name.is_a?(Symbol) || name.is_a?(String)
+    end
+
+    # enum :status, {...} | enum :status, [...] | enum :status, a: 0, b: 1 | enum status: {...}, _prefix: true
+    def enum(node, unit)
+      args, options = Literal.arguments(node)
+      values = options.reject { |key, _| key.start_with?("_") || ENUM_OPTIONS.include?(key) }
+      pairs = if args.any?
+                [[Literal.value(args[0]), args[1] ? Literal.value(args[1]) : keyword_values(values)]]
+              else
+                values.map { |key, value| [key, Literal.value(value)] }
+              end
+      pairs.each do |name, values|
+        next skip(unit, node, "#{unit.model.name} enum :#{name}: non-literal values, skipped") unless values.is_a?(Hash) || values.is_a?(Array)
+
+        unit.model.enums[name.to_s] = enum_labels(values)
+      end
+    end
+
+    # The values of `enum :status, a: 0, b: 1`, or UNKNOWN when there are none or one is not a literal.
+    def keyword_values(nodes)
+      values = nodes.transform_values { |node| Literal.value(node) }
+      values.any? && values.values.all? { |value| Literal.known?(value) } ? values : Literal::UNKNOWN
+    end
+
+    def enum_labels(values)
+      return values.map(&:to_s) if values.is_a?(Array)
+
+      values.map { |key, value| key.to_s == value.to_s ? key.to_s : "#{key} (#{value})" }
+    end
+
+    def add_include(node, unit)
+      return unless node.is_a?(Prism::CallNode) && node.name == :include && node.receiver.nil?
+
+      (node.arguments&.arguments || []).each do |arg|
+        name = Literal.constant_name(arg)
+        unit.model.includes << name if name
+      end
+    end
+
+    def skip(unit, node, message)
+      unit.warnings << Diagnostic.new(message: message, path: @path, line: node.location.start_line)
+      nil
+    end
+
+    # Constant lookup like Ruby's lexical scope: innermost scope first, then top level.
+    def resolve(name, scopes)
+      return nil unless name
+
+      name = name.delete_prefix("::")
+      scopes.reverse.map { |scope| "#{scope}::#{name}" }.find { |candidate| @units.key?(candidate) } ||
+        (@units.key?(name) ? name : nil)
+    end
+
+    def model?(name, seen = [])
+      unit = @units[name]
+      return false if unit.nil? || unit.concern || seen.include?(name)
+
+      superclass = unit.model.superclass
+      return false unless superclass
+
+      resolved = resolve(superclass, unit.scopes[0...-1])
+      unit.model.superclass = resolved || superclass
+      return model?(resolved, seen + [name]) if resolved
+
+      ROOTS.include?(superclass.delete_prefix("::")) || IMPLICIT_ABSTRACT.include?(superclass)
+    end
+
+    # A concern's `included do` declarations (and the concerns it includes) land on the class.
+    def apply_concerns(unit, seen = [])
+      model = unit.model
+      unit.model.includes.each do |name|
+        concern = @units[resolve(name, unit.scopes)]
+        next unless concern&.concern && !seen.include?(concern.model.name)
+
+        # Expanded on a copy, so the next class including this concern starts from it as written.
+        concern = copy(concern)
+        apply_concerns(concern, seen + [concern.model.name])
+        model.associations.unshift(*concern.model.associations)
+        model.attachments.unshift(*concern.model.attachments)
+        model.enums.merge!(concern.model.enums) { |_key, own, _theirs| own }
+        unit.warnings.concat(concern.warnings)
+      end
+    end
+
+    def copy(unit)
+      model = unit.model.dup
+      model.associations = model.associations.dup
+      model.attachments = model.attachments.dup
+      model.enums = model.enums.dup
+      unit.dup.tap { |u| u.model = model; u.warnings = u.warnings.dup }
+    end
+  end
+end

data/lib/rails2qdbd/output.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Rails2qdbd
+  # Writes converter results to disk, or reports how the disk differs (for --check).
+  # Only files starting with the generated header are ever replaced or removed.
+  module Output
+    module_function
+
+    # path: a .txt file (single result file) or a directory. Returns the paths actually written.
+    # Raises Error, writing nothing, when a destination exists without the generated header.
+    def write(result, path)
+      foreign = planned(result, path).keys.select { |file| File.exist?(file) && !generated?(file) }
+      if foreign.any?
+        raise Error, "not generated by rails2qdbd, left untouched (move or delete them to regenerate): #{foreign.join(', ')}"
+      end
+
+      planned(result, path).filter_map do |file, text|
+        next if File.file?(file) && File.read(file) == text
+
+        FileUtils.mkdir_p(File.dirname(file))
+        File.write(file, text)
+        file
+      end.tap { leftovers(result, path).each { |file| File.delete(file) } }
+    end
+
+    # Human-readable list of differences; empty means up to date.
+    def stale(result, path)
+      problems = planned(result, path).filter_map do |file, text|
+        if !File.file?(file) then "#{file} (missing)"
+        elsif !generated?(file) then "#{file} (not generated by rails2qdbd)"
+        elsif File.read(file) != text then "#{file} (out of date)"
+        end
+      end
+      problems + leftovers(result, path).map { |file| "#{file} (no longer generated)" }
+    end
+
+    def planned(result, path)
+      return { path => result.files.values.first } if single_file?(path)
+
+      result.files.sort.to_h { |name, text| [File.join(path, name), text] }
+    end
+
+    # Generated files in the output directory that this result no longer produces.
+    def leftovers(result, path)
+      return [] if single_file?(path) || !File.directory?(path)
+
+      Dir.glob("*.txt", base: path).sort.filter_map do |name|
+        file = File.join(path, name)
+        file if !result.files.key?(name) && generated?(file)
+      end
+    end
+
+    def generated?(file) = File.file?(file) && File.foreach(file).first.to_s.start_with?(Writer::HEADER)
+
+    def single_file?(path) = path.end_with?(".txt")
+  end
+end

data/lib/rails2qdbd/resolver.rb

@@ -0,0 +1,266 @@
+# frozen_string_literal: true
+
+module Rails2qdbd
+  # Derives relationships and documentation notes from the schema and the models.
+  # Database foreign keys come first and win every conflict.
+  class Resolver
+    include Catalog
+
+    MODEL_NOTE = "relationship from model association (no database constraint)"
+
+    # relationships: { [from_table, from_column] => Relationship }
+    # table_notes: { table => [String] }; column_notes: { table => { column => [String] } }
+    Resolution = Struct.new(:relationships, :table_notes, :column_notes, :diagnostics, keyword_init: true)
+
+    # excluded: tables left out of the output; relationships into them become notes.
+    def initialize(schema, models, inflector:, excluded: ->(_table) { false })
+      @schema = schema
+      @models = models
+      @inflector = inflector
+      @excluded = excluded
+    end
+
+    def resolve
+      @relationships = {}
+      @hints = Hash.new { |hash, key| hash[key] = [] } # [table, column] => [:has_one | :has_many]
+      @polymorphic = {} # [table, column] => { type:, targets: [] }
+      @table_notes = Hash.new { |hash, key| hash[key] = [] }
+      @column_notes = Hash.new { |hash, table| hash[table] = Hash.new { |h, column| h[column] = [] } }
+      @attachments = Hash.new { |hash, key| hash[key] = [] } # table => [[name, :one | :many]]
+      @diagnostics = []
+      # The model owning each table (first by name), for association targets.
+      @table_models = @models.values.reject { |model| model.abstract || sti_child?(model) }
+                             .each_with_object({}) { |model, index| index[table_for(model)] ||= model }
+
+      @schema.foreign_keys.each { |fk| add_database_fk(fk) }
+      @models.each_value { |model| resolve_model(model) unless model.abstract }
+      finish
+    end
+
+    # The table a model reads: STI subclasses use their base class's table.
+    def table_for(model)
+      return nil if model.abstract
+
+      return table_for(@models[model.superclass]) if sti_child?(model)
+
+      model.table_name || @inflector.tableize(model.name)
+    end
+
+    private
+
+    # A subclass of a concrete model shares its table (single-table inheritance).
+    def sti_child?(model) = !!@models[model.superclass]&.then { |parent| !parent.abstract }
+
+    def add_database_fk(fk)
+      label = "foreign key #{fk.from_table}.#{fk.from_column} -> #{fk.to_table}.#{fk.to_column}"
+      problem = missing(fk.from_table, fk.from_column) || missing(fk.to_table, fk.to_column)
+      return @diagnostics << Diagnostic.new(message: "#{label}: #{problem}, skipped") if problem
+
+      @relationships[[fk.from_table, fk.from_column]] ||= Relationship.new(
+        from_table: fk.from_table, from_column: fk.from_column, to_table: fk.to_table, to_column: fk.to_column, source: :database,
+      )
+    end
+
+    # Declarations of abstract parents apply to each subclass, resolved as the subclass's own.
+    def resolve_model(model)
+      table = table_for(model)
+      declared = [*abstract_ancestors(model), model]
+      declared.flat_map(&:associations).each { |association| resolve_association(model, table, association) }
+      return unless @schema.tables.key?(table)
+
+      declared.map(&:enums).reduce(:merge).each do |column, values|
+        next if (schema_column = @schema.tables[table].column(column)).nil? || schema_column.enum_values
+
+        @column_notes[table][column] << "enum: #{values.join(', ')}"
+      end
+      attachments = declared.flat_map(&:attachments)
+      @attachments[table].concat(attachments)
+      active_storage_target(model) if attachments.any?
+    end
+
+    # Abstract superclasses, outermost first. An STI child stops at its concrete parent, whose own
+    # declarations are resolved with it.
+    def abstract_ancestors(model)
+      chain = []
+      while (parent = @models[model.superclass]) && parent.abstract && !chain.include?(parent)
+        chain.unshift(parent)
+        model = parent
+      end
+      chain
+    end
+
+    # Active Storage's own models live in Rails, so its polymorphic record is described from
+    # the app side: every model with has_one_attached / has_many_attached is a target.
+    def active_storage_target(model)
+      key = %w[active_storage_attachments record_id]
+      return unless @schema.tables[key.first]&.column(key.last)
+
+      entry = (@polymorphic[key] ||= { type: "record_type", targets: [] })
+      entry[:targets] |= [model.name]
+    end
+
+    def resolve_association(model, table, association)
+      context = [model, association]
+      return warn(context, "table #{table} not found") unless @schema.tables.key?(table)
+
+      case association.macro
+      when :belongs_to then belongs_to(context, table)
+      when :has_many, :has_one then has_many(context, table)
+      when :has_and_belongs_to_many then habtm(context, table)
+      end
+    end
+
+    def belongs_to(context, table)
+      _, association = context
+      options = association.options
+      column = options[:foreign_key] || "#{association.name}_id"
+      return polymorphic_belongs_to(table, column, options[:foreign_type] || "#{association.name}_type") if options[:polymorphic]
+
+      target = target_table(context, options[:class_name] || @inflector.camelize(association.name)) or return
+      add_model_edge(context, table, column, target, options[:primary_key] || primary_key(target, model_for_table(target)))
+    end
+
+    def has_many(context, table)
+      model, association = context
+      options = association.options
+      return if options[:through]
+      return polymorphic_target(context) if options[:as]
+
+      default_class = association.macro == :has_many ? @inflector.singularize(association.name) : association.name
+      target = target_table(context, options[:class_name] || @inflector.camelize(default_class)) or return
+      column = options[:foreign_key] || @inflector.foreign_key(model.name)
+      @hints[[target, column]] << association.macro if add_model_edge(context, target, column, table,
+                                                                      options[:primary_key] || primary_key(table, model))
+    end
+
+    def habtm(context, table)
+      model, association = context
+      options = association.options
+      target = target_table(context, options[:class_name] || @inflector.camelize(@inflector.singularize(association.name))) or return
+      join = options[:join_table] || [table, target].sort.join("\0").gsub(/^(.*_)(.+)\0\1(.+)/, '\1\2_\3').tr("\0", "_")
+      return warn(context, "join table #{join} not found") unless @schema.tables.key?(join)
+
+      add_model_edge(context, join, options[:foreign_key] || @inflector.foreign_key(model.name), table, primary_key(table, model))
+      target_class = options[:class_name] || @inflector.camelize(@inflector.singularize(association.name))
+      add_model_edge(context, join, options[:association_foreign_key] || @inflector.foreign_key(target_class),
+                     target, primary_key(target, model_for_table(target)))
+    end
+
+    def polymorphic_belongs_to(table, column, type_column)
+      return unless @schema.tables[table].column(column)
+
+      @polymorphic[[table, column]] ||= { type: type_column, targets: [] }
+    end
+
+    # has_many :comments, as: :commentable -> Model is one of comments.commentable_id's targets.
+    def polymorphic_target(context)
+      model, association = context
+      options = association.options
+      target = target_table(context, options[:class_name] || @inflector.camelize(@inflector.singularize(association.name))) or return
+      key = [target, options[:foreign_key] || "#{options[:as]}_id"]
+      problem = missing(*key)
+      return warn(context, problem) if problem
+
+      entry = (@polymorphic[key] ||= { type: options[:foreign_type] || "#{options[:as]}_type", targets: [] })
+      entry[:targets] |= [model.name]
+    end
+
+    # Rails-like class lookup (namespace first), else a table named after the class.
+    def target_table(context, class_name)
+      model, = context
+      scopes = model.name.split("::")[0...-1]
+      candidates = scopes.size.downto(0).map { |n| [*scopes.first(n), class_name.delete_prefix("::")].join("::") }
+      found = candidates.filter_map { |name| @models[name] }.first
+      table = found ? table_for(found) : @inflector.tableize(class_name)
+      return table if @schema.tables.key?(table)
+
+      warn(context, found ? "table #{table} not found" : "class #{class_name} not found")
+    end
+
+    def model_for_table(table) = @table_models[table]
+
+    # A composite key cannot be an association target, so only a single-column key counts.
+    def primary_key(table, model)
+      return model.primary_key if model&.primary_key.is_a?(String)
+
+      @schema.tables[table].primary_key.then { |pk| pk.size == 1 ? pk.first : "id" }
+    end
+
+    # true when the edge exists (new or already known with the same target).
+    def add_model_edge(context, from_table, from_column, to_table, to_column)
+      problem = missing(from_table, from_column) || missing(to_table, to_column)
+      return warn(context, problem) && false if problem
+
+      key = [from_table, from_column]
+      existing = @relationships[key]
+      if existing && [existing.to_table, existing.to_column] != [to_table, to_column]
+        source = existing.source == :database ? "the database foreign key" : "another association"
+        winner = existing.source == :database ? "the database" : "the first"
+        return warn(context, "points to #{to_table}.#{to_column} but #{source} points to " \
+                             "#{existing.to_table}.#{existing.to_column}; using #{winner}", skipped: false) && false
+      end
+
+      @relationships[key] ||= Relationship.new(from_table: from_table, from_column: from_column, to_table: to_table,
+                                               to_column: to_column, source: :model)
+      true
+    end
+
+    def missing(table, column)
+      return "table #{table} not found" unless @schema.tables.key?(table)
+
+      "column #{table}.#{column} not found" unless @schema.tables[table].column(column)
+    end
+
+    def warn(context, problem, skipped: true)
+      model, association = context
+      @diagnostics << Diagnostic.new(message: "#{model.name} #{association.macro} :#{association.name}: #{problem}#{', skipped' if skipped}",
+                                     path: association.path, line: association.line)
+      nil
+    end
+
+    def finish
+      drop_excluded
+      @relationships.each do |key, relationship|
+        relationship.cardinality = :one_to_one if one_to_one?(key)
+        @column_notes[key.first][key.last] << MODEL_NOTE if relationship.source == :model
+      end
+      @polymorphic.sort.each do |(table, column), entry|
+        targets = entry[:targets].sort
+        @column_notes[table][column] << "polymorphic (type in #{entry[:type]})#{": #{targets.join(', ')}" if targets.any?}"
+      end
+      sti_notes
+      @attachments.each do |table, attachments|
+        next if attachments.empty?
+
+        @table_notes[table] << "attachments: #{attachments.uniq.map { |name, kind| "#{name} (#{kind})" }.join(', ')}"
+      end
+      Resolution.new(relationships: @relationships, table_notes: plain(@table_notes),
+                     column_notes: plain(@column_notes).transform_values { |columns| plain(columns) }, diagnostics: @diagnostics)
+    end
+
+    def drop_excluded
+      @relationships.reject! do |(table, column), relationship|
+        next false unless @excluded.call(table) || @excluded.call(relationship.to_table)
+
+        @column_notes[table][column] << "references #{relationship.to_table} (excluded)" unless @excluded.call(table)
+        true
+      end
+    end
+
+    def one_to_one?((table, column))
+      unique = @schema.tables[table].indexes.any? { |index| index.single_column? && index.unique && index.columns == [column] }
+      hints = @hints[[table, column]]
+      unique || (hints.include?(:has_one) && !hints.include?(:has_many))
+    end
+
+    def sti_notes
+      subclasses = @models.values.select { |model| sti_child?(model) }
+      subclasses.group_by { |model| table_for(model) }.sort.each do |table, models|
+        @table_notes[table].unshift("STI: #{models.map(&:name).sort.join(', ')}") if @schema.tables.key?(table)
+      end
+    end
+
+    # Drops the default procs so callers get ordinary hashes.
+    def plain(hash) = {}.merge(hash.reject { |_, value| value.empty? })
+  end
+end