rom 5.4.1 → 6.0.0.alpha1

data/lib/rom/lint/gateway.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require "rom/lint/linter"
+
+module ROM
+  module Lint
+    # Ensures that a [ROM::Gateway] extension provides datasets through the
+    # expected methods
+    #
+    # @api public
+    class Gateway < ROM::Lint::Linter
+      # The gateway identifier e.g. +:memory+
+      #
+      # @api public
+      attr_reader :identifier
+
+      # The gateway class
+      #
+      # @api public
+      attr_reader :gateway
+
+      # The optional URI
+      #
+      # @api public
+      attr_reader :uri
+
+      # Gateway instance used in lint tests
+      #
+      # @api private
+      attr_reader :gateway_instance
+
+      # Create a gateway linter
+      #
+      # @param [Symbol] identifier
+      # @param [Class] gateway
+      # @param [String] uri optional
+      def initialize(identifier, gateway, uri = nil)
+        @identifier = identifier
+        @gateway = gateway
+        @uri = uri
+        @gateway_instance = setup_gateway_instance
+      end
+
+      # Lint: Ensure that +gateway+ setups up its instance
+      #
+      # @api public
+      def lint_gateway_setup
+        return if gateway_instance.instance_of? gateway
+
+        complain <<-STRING
+          #{gateway}.setup must return a gateway instance but
+          returned #{gateway_instance.inspect}
+        STRING
+      end
+
+      # Lint: Ensure that +gateway_instance+ responds to +[]+
+      #
+      # @api public
+      def lint_dataset_reader
+        return if gateway_instance.respond_to? :[]
+
+        complain "#{gateway_instance} must respond to []"
+      end
+
+      # Lint: Ensure that +gateway_instance+ responds to +dataset?+
+      #
+      # @api public
+      def lint_dataset_predicate
+        return if gateway_instance.respond_to? :dataset?
+
+        complain "#{gateway_instance} must respond to dataset?"
+      end
+
+      # Lint: Ensure +gateway_instance+ supports +transaction+ interface
+      #
+      # @api public
+      def lint_transaction_support
+        result = gateway_instance.transaction { 1 }
+
+        complain "#{gateway_instance} must return the result of a transaction block" if result != 1
+
+        gateway_instance.transaction do |t|
+          t.rollback!
+
+          complain "#{gateway_instance} must interrupt a transaction on rollback"
+        end
+      end
+
+      # Lint: Ensure +gateway_instance+ returns adapter name
+      def lint_adapter_reader
+        if gateway_instance.adapter != identifier
+          complain "#{gateway_instance} must have the adapter identifier set to #{identifier.inspect}"
+        end
+      rescue MissingAdapterIdentifierError
+        complain "#{gateway_instance} is missing the adapter identifier"
+      end
+
+      private
+
+      # Setup gateway instance
+      #
+      # @api private
+      def setup_gateway_instance
+        if uri
+          ROM::Gateway.setup(identifier, uri)
+        else
+          ROM::Gateway.setup(identifier)
+        end
+      end
+
+      # Run Gateway#disconnect
+      #
+      # @api private
+      def after_lint
+        super
+        gateway_instance.disconnect
+      end
+    end
+  end
+end

data/lib/rom/lint/linter.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module ROM
+  module Lint
+    # Base class for building linters that check source code
+    #
+    # Linters are used by authors of ROM adapters to verify that their
+    # integration complies with the ROM api.
+    #
+    # Most of the time, authors won't need to construct linters directly
+    # because the provided test helpers will automatically run when required
+    # in tests and specs.
+    #
+    # @example
+    #   require 'rom/lint/spec'
+    #
+    #
+    # @api public
+    class Linter
+      # A failure raised by +complain+
+      Failure = Class.new(StandardError)
+
+      # Iterate over all lint methods
+      #
+      # @yield [String, ROM::Lint]
+      #
+      # @api public
+      def self.each_lint
+        return to_enum unless block_given?
+
+        lints.each { |lint| yield lint, self }
+      end
+
+      # Run a lint method
+      #
+      # @param [String] name
+      #
+      # @raise [ROM::Lint::Linter::Failure] if linting fails
+      #
+      # @api public
+      def lint(name)
+        before_lint
+        public_send name
+        after_lint
+        true # for assertions
+      end
+
+      # Return a list a lint methods
+      #
+      # @return [String]
+      #
+      # @api private
+      def self.lints
+        public_instance_methods(true).grep(/^lint_/).map(&:to_s)
+      end
+
+      private
+
+      # Raise a failure if a lint verification fails
+      #
+      # @raise [ROM::Lint::Linter::Failure]
+      #
+      # @api private
+      def complain(*args)
+        raise Failure, *args
+      end
+
+      # Hook method executed before each lint method run
+      #
+      # @api private
+      def before_lint; end
+
+      # Hook method executed after each lint method run
+      #
+      # @api private
+      def after_lint; end
+    end
+  end
+end

data/lib/rom/lint/spec.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "rom/lint/gateway"
+require "rom/lint/enumerable_dataset"
+
+RSpec.shared_examples "a rom gateway" do
+  ROM::Lint::Gateway.each_lint do |name, linter|
+    it name do
+      result = linter.new(identifier, gateway, uri).lint(name)
+      expect(result).to be_truthy
+    end
+  end
+end
+
+RSpec.shared_examples "a rom enumerable dataset" do
+  ROM::Lint::EnumerableDataset.each_lint do |name, linter|
+    it name do
+      result = linter.new(dataset, data).lint(name)
+      expect(result).to be_truthy
+    end
+  end
+end

data/lib/rom/lint/test.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "rom/lint/gateway"
+require "rom/lint/enumerable_dataset"
+
+module ROM
+  module Lint
+    # A module that helps to define test methods
+    module Test
+      # Defines a test method converting lint failures to assertions
+      #
+      # @param [String] name
+      #
+      # @api private
+      def define_test_method(name, &block)
+        define_method "test_#{name}" do
+          instance_eval(&block)
+        rescue ROM::Lint::Linter::Failure => e
+          raise Minitest::Assertion, e.message
+        end
+      end
+    end
+
+    # This is a simple lint-test for gateway class to ensure the
+    # basic interfaces are in place
+    #
+    # @example
+    #
+    #   class MyGatewayTest < Minitest::Test
+    #     include ROM::Lint::TestGateway
+    #
+    #     def setup
+    #       @gateway = MyGateway
+    #       @uri = "super_db://something"
+    #     end
+    #   end
+    #
+    # @api public
+    module TestGateway
+      extend ROM::Lint::Test
+
+      # Returns the gateway identifier e.g. +:memory+
+      #
+      # @api public
+      attr_reader :identifier
+
+      # Returns the gateway class
+      #
+      # @api public
+      attr_reader :gateway
+
+      # Returns gateway's URI e.g. "super_db://something"
+      #
+      # @api public
+      attr_reader :uri
+
+      ROM::Lint::Gateway.each_lint do |name, linter|
+        define_test_method name do
+          assert linter.new(identifier, gateway, uri).lint(name)
+        end
+      end
+    end
+
+    # This is a simple lint-test for a gateway dataset class to ensure the
+    # basic behavior is correct
+    #
+    # @example
+    #
+    #  class MyDatasetLintTest < Minitest::Test
+    #    include ROM::Lint::TestEnumerableDataset
+    #
+    #     def setup
+    #       @data  = [{ name: 'Jane', age: 24 }, { name: 'Joe', age: 25 }]
+    #       @dataset = MyDataset.new(@data, [:name, :age])
+    #     end
+    #   end
+    # @api public
+    module TestEnumerableDataset
+      extend ROM::Lint::Test
+
+      # Returns the dataset instance
+      #
+      # @api public
+      attr_reader :dataset
+
+      # Returns the expected data
+      #
+      # @api public
+      attr_reader :data
+
+      ROM::Lint::EnumerableDataset.each_lint do |name, linter|
+        define_test_method name do
+          assert linter.new(dataset, data).lint(name)
+        end
+      end
+    end
+  end
+end

data/lib/rom/loader.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "zeitwerk"
+
+require "rom/support/inflector"
+
+require "rom/types"
+require "rom/initializer"
+require "rom/loader"
+
+module ROM
+  # AutoRegistration is used to load component files automatically from the provided directory path
+  #
+  # @api public
+  class Loader
+    extend Initializer
+
+    NamespaceType = Types::Strict::Bool | Types.Instance(Module)
+
+    PathnameType = Types.Constructor(Pathname, &Kernel.method(:Pathname))
+
+    InflectorType = Types.Interface(:camelize)
+
+    ComponentDirs = Types::Strict::Hash.constructor { |hash| hash.transform_values(&:to_s) }
+
+    DEFAULT_MAPPING = {
+      relations: "relations",
+      mappers: "mappers",
+      commands: "commands"
+    }.freeze
+
+    # @!attribute [r] directory
+    #   @return [Pathname] The root path
+    param :root_directory, type: PathnameType.optional
+
+    # @!attribute [r] auto_load
+    #   @return [Boolean]
+    #     Whether files should be auto-loadable
+    option :auto_load, type: Types::Strict::Bool, default: -> { false }
+
+    # @!attribute [r] namespace
+    #   @return [Boolean,String]
+    #     The name of the top level namespace or true/false which
+    #     enables/disables default top level namespace inferred from the dir name
+    option :namespace, type: NamespaceType, default: -> { true }
+
+    # @!attribute [r] component_dirs
+    #   @return [Hash] component => dir-name map
+    option :component_dirs, type: ComponentDirs, default: -> { DEFAULT_MAPPING }
+
+    # @!attribute [r] inflector
+    #   @return [Dry::Inflector] String inflector
+    #   @api private
+    option :inflector, type: InflectorType, default: -> { Inflector }
+
+    # @!attribute [r] components
+    #   @return [ROM::Components]
+    #   @api private
+    option :components
+
+    # Load components
+    #
+    # @api private
+    def call
+      return if @loaded || root_directory.nil?
+
+      setup
+
+      backend.eager_load unless auto_load
+
+      @loaded = true
+    end
+
+    # @api private
+    def auto_load_component_file(type, key)
+      return unless component_dirs.include?(type)
+
+      const_parts = key.split(".").map { |name| inflector.camelize(name) }
+      const_parts.unshift(namespace_const_name) if namespace_const_name
+      const_name = const_parts.join("::")
+
+      inflector.constantize(const_name)
+    end
+
+    private
+
+    # @api private
+    def namespace_const_name
+      case namespace
+      when true
+        inflector.classify(root_directory.basename)
+      end
+    end
+
+    # @api private
+    def backend
+      @backend ||= Zeitwerk::Loader.new
+    end
+
+    # @api private
+    # rubocop:disable Metrics/AbcSize
+    def setup
+      backend.inflector = inflector
+
+      case namespace
+      when true
+        top_directory = root_directory.join("..").realpath
+
+        backend.push_dir(top_directory)
+
+        others = top_directory.children.select(&:directory?).reject { |dir| dir == root_directory }
+
+        others.each do |dir|
+          backend.ignore(dir)
+        end
+      when false
+        backend.push_dir(root_directory)
+      else
+        backend.push_dir(root_directory, namespace: namespace)
+      end
+
+      excluded_dirs.each do |dir|
+        backend.ignore(dir)
+      end
+
+      backend.on_load do |_, constant, path|
+        if (type = path_to_component_type(path))
+          begin
+            components.add(type, constant: constant, config: constant.config.component)
+          rescue StandardError => e
+            raise "Failed to load #{constant} from #{path}: #{e.message}"
+          end
+        end
+      end
+
+      backend.setup
+    end
+    # rubocop:enable Metrics/AbcSize
+
+    # @api private
+    def path_to_component_type(path)
+      return unless File.file?(path)
+
+      component_dirs
+        .detect { |_, dir|
+          path.start_with?(root_directory.join(dir).to_s)
+        }
+        &.first
+    end
+
+    # @api private
+    def excluded_dirs
+      root_directory
+        .children
+        .select(&:directory?)
+        .reject { |dir| component_dirs.values.include?(dir.basename.to_s) }
+        .map { |name| root_directory.join(name) }
+    end
+  end
+end