pg_trunk 0.1.0

data/lib/pg_trunk/core/dependencies_resolver.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module PGTrunk
+  # @private
+  # Resolve dependencies between inter-dependent objects,
+  # identified by database `#oid` and comparable to each other.
+  #
+  # The method builds the sorted list:
+  # - parent objects moved before their dependants.
+  # - independent objects keeps their original order.
+  #
+  # We have no expectations about the natural order here.
+  # @see [PGTrunk::ObjectDefinitions::Operation]
+  class DependenciesResolver
+    class << self
+      # Resolve dependencies between objects
+      # @param  [Array<Enumerable, #oid>] objects The list of objects
+      # @return [Array<#oid>] The sorted list of objects
+      # @raise  [Dependencies::CycleError] if dependencies contain a cycle
+      def resolve(objects)
+        new(objects, dependencies).send(:sorted)
+      end
+
+      private
+
+      def query
+        <<~SQL.squish
+          SELECT child, array_agg(parent) AS parents
+          FROM (
+            SELECT
+              d.objid AS child,
+              d.refobjid AS parent
+            FROM pg_depend d
+              JOIN pg_trunk e1 ON d.objid = e1.oid
+              JOIN pg_trunk e2 ON d.refobjid = e2.oid
+            WHERE d.objsubid IS NULL
+          ) dependencies
+          GROUP BY child;
+        SQL
+      end
+
+      # Extract dependencies between given oids from the database
+      def dependencies
+        ActiveRecord::Base
+          .connection
+          .execute(query)
+          .each_with_object({}) do |i, obj|
+            child = i["child"].to_i
+            parents = i["parents"].scan(/\d+/).map(&:to_i)
+            obj[child] = parents.uniq
+          end
+      end
+    end
+
+    private
+
+    # @param [Array<Comparable, #oid>] objects Objects to sort
+    # @param [Hash<{Integer => Array<Integer>}] parents Dependencies between oid-s
+    def initialize(objects, parents)
+      @objects = objects
+      @parents = parents.transform_values do |oids|
+        # preserve the original order of objects
+        objects.each_with_object([]) do |obj, list|
+          list << obj if oids.include?(obj.oid)
+        end
+      end
+    end
+
+    attr_reader :objects, :parents
+
+    def visited
+      @visited ||= {}
+    end
+
+    def index
+      @index ||= objects.each_with_object({}) { |obj, idx| idx[obj.oid] = obj }
+    end
+
+    # Use topological sorting algorithm to resolve dependencies
+    # @return [Array<#oid>]
+    def sorted
+      @sorted ||= [].tap do |output|
+        while (object = next_unvisited)
+          visit(object, output)
+        end
+      end
+    end
+
+    def next_unvisited
+      objects.find { |object| !visited[object.oid] }
+    end
+
+    def visit(object, output)
+      return if visited[object.oid]
+
+      parents[object.oid]&.each { |parent| visit(parent, output) }
+      visited[object.oid] = true
+      output << object
+    end
+  end
+end

data/lib/pg_trunk/core/generators.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: false
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+# @private
+# @abstract
+# Module to build object-specific generators
+module PGTrunk::Generators
+  extend ActiveSupport::Concern
+
+  class << self
+    # Add new generator for given operation
+    # @param [Class < PGTrunk::Operation] operation
+    def register(operation)
+      klass = build_generator(operation)
+      class_name = klass.name.split("::").last.to_sym
+      remove_const(class_name) if const_defined?(class_name)
+      const_set(class_name, klass)
+    end
+
+    # rubocop: disable Metrics/MethodLength
+    def build_generator(operation)
+      Class.new(Rails::Generators::NamedBase) do
+        include Rails::Generators::Migration
+        include PGTrunk::Generators
+
+        # Add the same arguments as in ruby method
+        operation.ruby_params.each do |name|
+          argument(name, **operation.attributes[name])
+        end
+
+        # Add the same options as in ruby method
+        operation.attributes.except(*operation.ruby_params).each do |name, opts|
+          class_option(name, **opts)
+        end
+
+        # The only command of the generator is to create a migration file
+        create_command(:create_migration_file)
+      end
+    end
+    # rubocop: enable Metrics/MethodLength
+  end
+
+  class_methods do
+    # @!attribute [r] fetcher The module including +PGTrunk::BaseFetcher+
+    attr_accessor :operation
+
+    # The name of the generated object like `foreign_key`
+    # for the `add_foreign_key` operation so that the command
+    #
+    #   rails g foreign_key 'users', 'roles'
+    #
+    # to build the migration containing
+    #
+    #   def change
+    #     add_foreign_key 'users', 'roles'
+    #   end
+    #
+    def object_name
+      @object_name ||= operation.object.singularize
+    end
+
+    # Use the name of the object as a name of the generator class
+    def name
+      @name ||= "PGTrunk::Generators::#{object_name.camelize}"
+    end
+
+    # The name of the operation to be added to the migration
+    def operation_name
+      @operation_name ||= operation.ruby_name
+    end
+
+    # Ruby handler to add positional arguments to options
+    def handle(*arguments, **options)
+      options.ruby_params.zip(arguments).merge(options)
+    end
+
+    def next_migration_number(dir)
+      ::ActiveRecord::Generators::Base.next_migration_number(dir)
+    end
+  end
+
+  def create_migration_file
+    file_name = "db/migrate/#{migration_number}_#{migration_name}.rb"
+    file = create_migration(file_name, nil, {}) do
+      <<~RUBY
+        # frozen_string_literal: true
+
+        class #{migration_name.camelize} < #{migration_base}
+          def change
+            #{command}
+          end
+        end
+      RUBY
+    end
+    Rails::Generators.add_generated_file(file)
+  end
+
+  private
+
+  def current_version
+    return @current_version if instance_variable_defined?(:@current_version)
+
+    @current_version = nil
+    return unless ActiveRecord::Migration.respond_to?(:current_version)
+
+    @current_version = ActiveRecord::Migration.current_version
+  end
+
+  # Build the name of the migration from given params like:
+  #
+  #   rails g foreign_key 'users', 'roles'
+  #
+  # to generate the migration named as:
+  #
+  #   class AddForeignKeyUsersRoles < ::ActiveRecord::Migration[6.2]
+  #     # ...
+  #   end
+  def migration_name
+    @migration_name ||= [
+      self.class.operation_name,
+      *(self.class.operation.ruby_params.map { |p| send(p) }),
+    ].join("_")
+  end
+
+  def migration_base
+    @migration_base ||= "::ActiveRecord::Migration".tap do |mb|
+      next if Rails::Version::MAJOR < "5"
+
+      mb << "[#{current_version}]" if current_version.present?
+    end
+  end
+
+  def command
+    opts = self.class.handle(*arguments, **options.symbolize_keys)
+    operation = self.class.operation.new(opts)
+    operation.to_ruby.indent(4).strip
+  end
+end

data/lib/pg_trunk/core/operation/attributes.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+class PGTrunk::Operation
+  # @private
+  # Define getters/setters for the operation attributes
+  module Attributes
+    extend ActiveSupport::Concern
+    include ActiveModel::Model
+    include ActiveModel::Attributes
+
+    # The special undefined value for getters/setters
+    # to distinct it from the explicitly provided `nil`.
+    UNDEFINED = Object.new.freeze
+    private_constant :UNDEFINED
+
+    class_methods do
+      # list of aliases for attributes
+      def attr_aliases
+        @attr_aliases ||= {}
+      end
+
+      # Add an attribute to the operation
+      def attribute(name, type, default: nil, aliases: nil)
+        # prevent mutation of the default arrays, hashes etc.
+        default = default.freeze if default.respond_to?(:freeze)
+        super(name, type, default: default, &nil)
+        # add the private attribute for the previous value
+        attr_reader :"from_#{name}"
+
+        redefine_getter(name)
+        Array(aliases).each { |key| attr_aliases[key.to_sym] = name.to_sym }
+        name.to_sym
+      end
+
+      private
+
+      def redefine_getter(name)
+        getter = instance_method(name)
+        define_method(name) do |value = UNDEFINED, *args, from: nil|
+          # fallback to the original getter w/o arguments
+          return getter.bind(self).call if value == UNDEFINED
+
+          # set a previous value to return to
+          instance_variable_set("@from_#{name}", from)
+
+          # arrays can be assigned as lists
+          value = [value, *args] if args.any?
+
+          send(:"#{name}=", value)
+        end
+      end
+
+      def inherited(klass)
+        klass.instance_variable_set(:@attr_aliases, attr_aliases)
+        super
+      end
+    end
+
+    def initialize(**opts)
+      # enable aliases during the initialization
+      self.class.attr_aliases.each do |a, n|
+        opts[n] = opts.delete(a) if opts.key?(a)
+      end
+      # ignore unknown attributes (to simplify calls of `#invert`)
+      opts = opts.slice(*self.class.attribute_names.map(&:to_sym))
+
+      super(**opts)
+    end
+
+    # The hash of the operation's serialized attributes
+    def attributes
+      super.to_h do |k, v|
+        [k.to_sym, self.class.attribute_types[k].serialize(v)]
+      end
+    end
+    alias to_h attributes
+  end
+end

data/lib/pg_trunk/core/operation/callbacks.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+class PGTrunk::Operation
+  # @private
+  # Enable to fulfill/generate missed attributes
+  # using the `after_initialize` callback.
+  #
+  # The callback is invoked after the end of the normal
+  # initialization and applying a block with explicit settings.
+  module Callbacks
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def callbacks
+        @callbacks ||= []
+      end
+
+      # Get or set the callback
+      def after_initialize(&block)
+        callbacks << block if block
+      end
+
+      private
+
+      def inherited(klass)
+        klass.instance_variable_set(:@callbacks, callbacks.dup)
+        super
+      end
+    end
+
+    private def initialize(*, **, &block)
+      # Explicitly assign all attributes from params/options.
+      super
+      # Explicitly assign attributes using a block.
+      block&.call(self)
+      # Apply +callback+ at the very end after all explicit assignments.
+      self.class.callbacks.each { |callback| instance_exec(&callback) }
+    end
+  end
+end

data/lib/pg_trunk/core/operation/generators.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+class PGTrunk::Operation
+  # @private
+  # Register attributes definition for later usage by generators
+  module Generators
+    extend ActiveSupport::Concern
+
+    class_methods do
+      # Gets or sets object name for the generator
+      def generates_object(name = nil)
+        @generates_object = name if name
+        @generates_object ||= nil
+      end
+
+      # The definitions of the attributes
+      # @return [Hash{Symbol => Hash{type:, default:, desc:}}]
+      def attributes
+        @attributes ||= {}
+      end
+
+      def attribute(name, type, default: nil, desc: nil, **opts)
+        name = name.to_sym
+        attributes[name] = {
+          type: gen_type(type),
+          default: default,
+          desc: desc,
+        }
+        super(name, type.to_sym, default: default, **opts)
+      end
+
+      private
+
+      def inherited(klass)
+        klass.instance_variable_set(:@attributes, attributes.dup)
+        super
+      end
+
+      # Convert the type to the acceptable by Rails::Generator
+      def gen_type(type)
+        case type.to_s
+        when "bool", "boolean"  then :boolean
+        when "integer", "float" then :numeric
+        when /^pg_trunk_array/  then :array
+        when /^pg_trunk_hash/   then :hash
+        else :string
+        end
+      end
+    end
+  end
+end

data/lib/pg_trunk/core/operation/inversion.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+class PGTrunk::Operation
+  # @private
+  # The exception to be thrown when reversed migration isn't valid
+  class IrreversibleMigration < ActiveRecord::IrreversibleMigration
+    private
+
+    def initialize(operation, inversion, *messages)
+      msg = "#{header(operation)}#{inverted(inversion)} #{footer(messages)}"
+      super(msg.strip)
+    end
+
+    def header(operation)
+      <<~MSG
+        This migration uses the operation:
+
+          #{operation.to_ruby.indent(2).strip}
+
+      MSG
+    end
+
+    def inverted(inversion)
+      return "which is not automatically reversible" unless inversion
+
+      <<~MSG.strip
+        whose inversion would be like:
+
+          #{inversion.to_ruby.indent(2).strip}
+
+        which is invalid
+      MSG
+    end
+
+    def footer(messages)
+      reasons = <<~REASONS.strip if messages.any?
+        for the following reasons:
+
+        #{messages.map { |m| "- #{m}" }.join("\n")}
+      REASONS
+
+      <<~MSG.strip
+        #{reasons}
+
+        To make the migration reversible you can either:
+        1. Define #up and #down methods in place of the #change method.
+        2. Use the #reversible method to define reversible behavior.
+      MSG
+    end
+  end
+
+  # @private
+  # Enable operations to be invertible
+  module Inversion
+    # @private
+    def invert!
+      invert&.tap do |i|
+        i.valid? || raise(IrreversibleMigration.new(self, i, *i.error_messages))
+      end
+    end
+
+    # @private
+    def irreversible!(option)
+      raise IrreversibleMigration.new(self, nil, <<~MSG.squish)
+        The operation with the `#{option}` option cannot be reversed
+          due to uncertainty of the previous state of the database.
+      MSG
+    end
+  end
+end

data/lib/pg_trunk/core/operation/registration.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+class PGTrunk::Operation
+  # @private
+  # Invoke all the necessary definitions
+  # in the modules included to Rails via Railtie
+  module Registration
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def from_sql(&block)
+        super.tap { register_dumper if block }
+      end
+
+      def generates_object(name = nil)
+        super.tap { register_generator if name }
+      end
+
+      def method_added(name)
+        super
+      ensure
+        register_operation if name == :to_sql
+        register_inversion if name == :invert
+      end
+
+      private
+
+      def register_operation
+        # Add the method to statements as an entry point
+        PGTrunk::Statements.register(self)
+        # Add the shortcut to migration go get away with checking
+        # of the first parameter which could be NOT a table name.
+        PGTrunk::Migration.register(self)
+        # Record the direct operation
+        PGTrunk::CommandRecorder.register(self)
+      end
+
+      def register_inversion
+        # Record the inversion of the operation
+        PGTrunk::CommandRecorder.register_inversion(self)
+      end
+
+      def register_dumper
+        PGTrunk::SchemaDumper.register(self)
+      end
+
+      def register_generator
+        # skip registration in the runtime
+        return unless const_defined?("PGTrunk::Generators")
+
+        PGTrunk::Generators.register(self)
+      end
+    end
+  end
+end

data/lib/pg_trunk/core/operation/ruby_builder.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+class PGTrunk::Operation
+  # @private
+  # Build ruby snippet
+  class RubyBuilder
+    private def initialize(name, shortage: nil)
+      @args = []
+      @lines = []
+      @name = name&.to_s
+      @opts = []
+      @shortage = shortage
+    end
+
+    # Add parameters to the method call
+    def ruby_param(*args, **opts)
+      @args = [*@args, *params(*args)]
+      @opts = [*@opts, *params(**opts)]
+    end
+
+    # Add line into a block
+    def ruby_line(meth, *args, **opts)
+      return if meth.blank?
+      return if args.first.nil?
+
+      @lines << build_line(meth, *args, **opts)
+    end
+
+    # Build the snippet
+    # @return [String]
+    def build
+      [header, *block].join(" ")
+    end
+
+    private
+
+    # Pattern to split lines by heredocs
+    HEREDOC = /<<~'?(?<head>[A-Z]+)'?.+(?<body>\n  .+)*\n\k<head>/.freeze
+
+    def build_line(meth, *args, **opts)
+      method_name = [shortage, meth].join(".")
+      method_params = params(*args, **opts)
+      line = [method_name, *method_params].join(" ")
+      return single_line(line).indent(2) unless block_given?
+
+      builder = self.class.new(line, shortage: "f")
+      yield(builder)
+      builder.build.indent(2)
+    end
+
+    # Finalize line containing a heredoc args
+    #   "body <<~'SQL'.chomp\n  foo\nSQL, from: <<~'SQL'.chomp\n  bar\nSQL"
+    #   "body <<~'SQL'.chomp, from: <<~'SQL'.chomp\n  foo\nSQL\n  bar\nSQL"
+    def single_line(text)
+      parts = text.partition(HEREDOC)
+      (
+        parts.map { |p| p[/^.+/] } + parts.map { |p| p[/\n(\n|.)*$/] }
+      ).compact.join
+    end
+
+    def shortage
+      @shortage ||= @name.split("_").last.first
+    end
+
+    def format(value)
+      case value
+      when Hash   then value
+      when String then format_text(value)
+      when Array  then format_list(value)
+      else value.inspect
+      end
+    end
+
+    def format_text(text)
+      text = text.chomp
+      # prevent quoting interpolations and heredocs
+      return text if text[/^<<~|^%[A-Za-z][(]/]
+
+      long_text = text.size > 50 || text.include?("\n")
+      return "<<~'Q'.chomp\n#{text.indent(2)}\nQ" if long_text && text["\\"]
+      return "<<~Q.chomp\n#{text.indent(2)}\nQ" if long_text
+      return "%q(#{text})" if /\\|"/.match?(text)
+
+      text.inspect
+    end
+
+    def format_list(list)
+      case list.map(&:class).uniq
+      when [::String] then "%w[#{list.join(' ')}]"
+      when [::Symbol] then "%i[#{list.join(' ')}]"
+      else list
+      end
+    end
+
+    def params(*values, **options)
+      vals = values.map { |val| format(val) }
+      opts = options.compact.map { |key, val| "#{key}: #{format(val)}" }
+      [*vals, *opts].join(", ").presence
+    end
+
+    def header
+      method_params = [*@args, *@opts].join(", ").presence
+      line = [@name, *method_params].join(" ")
+      line << " do |#{shortage}|" if @lines.any?
+      single_line(line)
+    end
+
+    def block
+      [nil, *@lines, "end"].join("\n") if @lines.any?
+    end
+  end
+end