rubocop-flexport 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 21c9588d65a1cc1b11a85277a94b02caf3dd37bb067b8a2ae09b53da39052bb0
-  data.tar.gz: 2ca05dbe05457065dcfd40e703e6a9c29340fd44a20862df21364ebc1c31e76f
+  metadata.gz: 8b441520e98f7b859443aefbd06f3d9794600b702d8b70ad37f1a5a072898947
+  data.tar.gz: 0c3767638f4c7303b0ff941cdbf16a589b757628404ae9b9f3a2b5505a9c8f37
 SHA512:
-  metadata.gz: 375ce90040f7a4185de7bc785867b46574dbc04a24ac0f17d8d3213075b9f689c60aec9e127830aea48005f76ca3f8a8023948a792284f45460fc80ce704ff87
-  data.tar.gz: 560c5d8655494e752fae1db186c5c7ee1d514fa938fb977c07d09a1c87b9edcffc17d9bec31aa6b42a25436df480f63e70caee00bc3b52f3cdd786cb18962aaf
+  metadata.gz: '08541d28bbedcf79eb1e570b97de445b965eed4c6ed266a4d6333bed6904f6e07ae63e2286a05607660cb7771829bddb830785a4565af1222eb4cb9f46f4d321'
+  data.tar.gz: a4ca03afba08fc095a8e6f152abe7ee8527b1eb80cd55f34a7d5c95bd4f86a46b34cb389d5d4af9cd1fc21fa13d30ca8624d79aa8f0c0f870c2a3e93247f4e2d

data/config/default.yml

@@ -1,3 +1,11 @@
+Flexport/EngineApiBoundary:
+  Description: 'Use Rails Engine APIs instead of arbitrary code access.'
+  Enabled: false
+  VersionAdded: '0.3.0'
+  EnginesPath: 'engines/'
+  UnprotectedEngines: []
+  EngineSpecificOverrides: []
+
 Flexport/GlobalModelAccessFromEngine:
   Description: 'Do not directly access global models from within Rails Engines.'
   Enabled: false

data/lib/rubocop/cop/flexport/engine_api_boundary.rb

@@ -0,0 +1,320 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Flexport
+      # This cop prevents code outside of a Rails Engine from directly
+      # accessing the engine without going through an API. The goal is
+      # to improve modularity and enforce separation of concerns.
+      #
+      # # Defining an engine's API
+      #
+      # The cop looks inside an engine's `api/` directory to determine its
+      # API. API surface can be defined in two ways:
+      #
+      # - Add source files to `api/`. Code defined in these modules
+      #   will be accessible outside your engine. For example, adding
+      #   `api/foo_service.rb` will allow code outside your engine to
+      #   invoke eg `MyEngine::Api::FooService.bar(baz)`.
+      # - Create a `_whitelist.rb` file in `api/`. Modules listed in
+      #   this file are accessible to code outside the engine. The file
+      #   must have this name and a particular format (see below).
+      #
+      # Both of these approaches can be used concurrently in the same engine.
+      # Due to Rails Engine directory conventions, the API directory should
+      # generally be located at eg `engines/my_engine/app/api/my_engine/api/`.
+      #
+      # # Usage
+      #
+      # This cop can be useful when splitting apart a legacy codebase.
+      # In particular, you might move some code into an engine without
+      # enabling the cop, and then enable the cop to see where the engine
+      # boundary is crossed. For each violation, you can either:
+      #
+      # - Expose new API surface from your engine
+      # - Move the violating file into the engine
+      # - Add the violating file to `_legacy_dependents.rb` (see below)
+      #
+      # The cop detects cross-engine associations as well as cross-engine
+      # module access.
+      #
+      # # Isolation guarantee
+      #
+      # This cop can be easily circumvented with metaprogramming, so it cannot
+      # strongly guarantee the isolation of engines. But it can serve as
+      # a useful guardrail during development, especially during incremental
+      # migrations.
+      #
+      # Consider using plain-old Ruby objects instead of ActiveRecords as the
+      # exchange value between engines. If one engine gets a reference to an
+      # ActiveRecord object for a model in another engine, it will be able
+      # to perform arbitrary reads and writes via associations and `.save`.
+      #
+      # # Example `api/_legacy_dependents.rb` file
+      #
+      # This file contains a burn-down list of source code files that still
+      # do direct access to an engine "under the hood", without using the
+      # API. It must have this structure.
+      #
+      # ```rb
+      # module MyEngine::Api::LegacyDependents
+      #   FILES_WITH_DIRECT_ACCESS = [
+      #     "app/models/some_old_legacy_model.rb",
+      #     "engines/other_engine/app/services/other_engine/other_service.rb",
+      #   ]
+      # end
+      # ```
+      #
+      # # Example `api/_whitelist.rb` file
+      #
+      # This file contains a list of modules that are allowed to be accessed
+      # by code outside the engine. It must have this structure.
+      #
+      # ```rb
+      # module MyEngine::Api::Whitelist
+      #   PUBLIC_MODULES = [
+      #     MyEngine::BarService,
+      #     MyEngine::BazService,
+      #     MyEngine::BatConstants,
+      #   ]
+      # end
+      # ```
+      #
+      # @example
+      #
+      #   # bad
+      #   class MyService
+      #     m = ReallyImportantSharedEngine::InternalModel.find(123)
+      #     m.destroy
+      #   end
+      #
+      #   # good
+      #   class MyService
+      #     ReallyImportantSharedEngine::Api::SomeService.execute(123)
+      #   end
+      #
+      # @example
+      #
+      #   # bad
+      #
+      #   class MyEngine::MyModel < ApplicationModel
+      #     has_one :foo_model, class_name: "SharedEngine::FooModel"
+      #   end
+      #
+      #   # good
+      #
+      #   class MyEngine::MyModel < ApplicationModel
+      #     # (No direct associations to models in API-protected engines.)
+      #   end
+      #
+      class EngineApiBoundary < Cop
+        include EngineApi
+
+        MSG = 'Direct access of %<engine>s engine. ' \
+              'Only access engine via %<engine>s::Api.'
+
+        def_node_matcher :rails_association_hash_args, <<-PATTERN
+          (send _ {:belongs_to :has_one :has_many} sym $hash)
+        PATTERN
+
+        def on_const(node)
+          # Sometimes modules/class are declared with the same name as an
+          # engine. For example, you might have:
+          #
+          #   /engines/foo
+          #   /app/graph/types/foo
+          #
+          # We ignore instead of yielding false positive for the module
+          # declaration in the latter.
+          return if in_module_or_class_declaration?(node)
+          # Similarly, you might have value objects that are named
+          # the same as engines like:
+          #
+          # Warehouse.new
+          #
+          # We don't want to warn on these cases either.
+          return if sending_method_to_namespace_itself?(node)
+
+          engine = extract_engine(node)
+          return unless engine
+          return if valid_engine_access?(node, engine)
+
+          add_offense(node, message: format(MSG, engine: engine))
+        end
+
+        def on_send(node)
+          rails_association_hash_args(node) do |assocation_hash_args|
+            class_name_node = extract_class_name_node(assocation_hash_args)
+            next if class_name_node.nil?
+
+            engine = extract_model_engine(class_name_node)
+            next if engine.nil?
+            next if valid_engine_access?(node, engine)
+
+            add_offense(class_name_node, message: format(MSG, engine: engine))
+          end
+        end
+
+        def external_dependency_checksum
+          engine_api_files_modified_time_checksum(engines_path)
+        end
+
+        private
+
+        def extract_engine(node)
+          return nil unless protected_engines.include?(node.const_name)
+
+          node.const_name
+        end
+
+        def engines_path
+          path = cop_config['EnginesPath']
+          path += '/' unless path.end_with?('/')
+          path
+        end
+
+        def protected_engines
+          @protected_engines ||= begin
+            unprotected = cop_config['UnprotectedEngines'] || []
+            unprotected_camelized = camelize_all(unprotected)
+            all_engines_camelized - unprotected_camelized
+          end
+        end
+
+        def all_engines_camelized
+          all_snake_case = Dir["#{engines_path}*"].map do |e|
+            e.gsub(engines_path, '')
+          end
+          camelize_all(all_snake_case)
+        end
+
+        def camelize_all(names)
+          names.map { |n| ActiveSupport::Inflector.camelize(n) }
+        end
+
+        def in_module_or_class_declaration?(node)
+          depth = 0
+          max_depth = 10
+          while node.const_type? && depth < max_depth
+            node = node.parent
+            depth += 1
+          end
+          node.module_type? || node.class_type?
+        end
+
+        def sending_method_to_namespace_itself?(node)
+          node.parent.send_type?
+        end
+
+        def valid_engine_access?(node, engine)
+          (
+            in_engine_file?(engine) ||
+            in_legacy_dependent_file?(engine) ||
+            through_api?(node) ||
+            whitelisted?(node, engine) ||
+            engine_specific_override?(node)
+          )
+        end
+
+        def extract_model_engine(class_name_node)
+          class_name = class_name_node.value
+          prefix = class_name.split('::')[0]
+          is_engine_model = prefix && protected_engines.include?(prefix)
+          is_engine_model ? prefix : nil
+        end
+
+        def extract_class_name_node(assocation_hash_args)
+          return nil unless assocation_hash_args
+
+          assocation_hash_args.each_pair do |key, value|
+            # Note: The "value.str_type?" is necessary because you can do this:
+            #
+            # TYPE_CLIENT = "Client".freeze
+            # belongs_to :recipient, class_name: TYPE_CLIENT
+            #
+            # The cop just ignores these cases. We could try to resolve the
+            # value of the const from the source but that seems brittle.
+            return value if key.value == :class_name && value.str_type?
+          end
+          nil
+        end
+
+        def current_engine
+          @current_engine ||= begin
+            file_path = processed_source.path
+            if file_path&.include?(engines_path)
+              parts = file_path.split(engines_path)
+              engine_dir = parts.last.split('/').first
+              ActiveSupport::Inflector.camelize(engine_dir) if engine_dir
+            end
+          end
+        end
+
+        def in_engine_file?(engine)
+          current_engine == engine
+        end
+
+        def in_legacy_dependent_file?(engine)
+          legacy_dependents = read_api_file(engine, :legacy_dependents)
+          # The file names are strings so we need to remove the escaped quotes
+          # on either side from the source code.
+          legacy_dependents = legacy_dependents.map do |source|
+            source.delete('"')
+          end
+          legacy_dependents.any? do |legacy_dependent|
+            processed_source.path.include?(legacy_dependent)
+          end
+        end
+
+        def through_api?(node)
+          node.parent&.const_type? && node.parent.children.last == :Api
+        end
+
+        def whitelisted?(node, engine)
+          whitelist = read_api_file(engine, :whitelist)
+          return false if whitelist.empty?
+
+          depth = 0
+          max_depth = 5
+          while node.const_type? && depth < max_depth
+            full_const_name = remove_leading_colons(node.source)
+            return true if whitelist.include?(full_const_name)
+
+            node = node.parent
+            depth += 1
+          end
+
+          false
+        end
+
+        def remove_leading_colons(str)
+          str.sub(/^:*/, '')
+        end
+
+        def read_api_file(engine, file_basename)
+          extract_api_list(engines_path, engine, file_basename)
+        end
+
+        def overrides_by_engine
+          overrides_by_engine = {}
+          raw_overrides = cop_config['EngineSpecificOverrides']
+          return overrides_by_engine if raw_overrides.nil?
+
+          raw_overrides.each do |raw_override|
+            engine = ActiveSupport::Inflector.camelize(raw_override['Engine'])
+            overrides_by_engine[engine] = raw_override['AllowedModels']
+          end
+          overrides_by_engine
+        end
+
+        def engine_specific_override?(node)
+          model_name = node.parent.source
+          model_names_allowed_by_override = overrides_by_engine[current_engine]
+          return false unless model_names_allowed_by_override
+
+          model_names_allowed_by_override.include?(model_name)
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/flexport_cops.rb

@@ -1,4 +1,7 @@
 # frozen_string_literal: true
 
+require_relative 'mixin/engine_api'
+
+require_relative 'flexport/engine_api_boundary'
 require_relative 'flexport/global_model_access_from_engine'
 require_relative 'flexport/new_global_model'

data/lib/rubocop/cop/mixin/engine_api.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require 'active_support/inflector'
+require 'digest/sha1'
+
+module RuboCop
+  module Cop
+    # Functionality for reading Rails Engine API declaration files.
+    module EngineApi
+      extend NodePattern::Macros
+
+      API_FILE_DETAILS = {
+        whitelist: {
+          file_basename: '_whitelist.rb',
+          array_matcher: :whitelist_array
+        },
+        legacy_dependents: {
+          file_basename: '_legacy_dependents.rb',
+          array_matcher: :legacy_dependents_array
+        }
+      }.freeze
+
+      def extract_api_list(engines_path, engine, api_file)
+        key = cache_key(engine, api_file)
+        @cache ||= {}
+        cached = @cache[key]
+        return cached if cached
+
+        details = API_FILE_DETAILS[api_file]
+
+        path = full_path(engines_path, engine, details)
+        return [] unless File.file?(path)
+
+        list = extract_array(path, details[:array_matcher])
+
+        @cache[key] = list
+        list
+      end
+
+      def engine_api_files_modified_time_checksum(engines_path)
+        api_files = Dir.glob(File.join(engines_path, '**/app/api/**/api/**/*'))
+        mtimes = api_files.sort.map { |f| File.mtime(f) }
+        Digest::SHA1.hexdigest(mtimes.join)
+      end
+
+      private
+
+      def full_path(engines_path, engine, details)
+        api_path(engines_path, engine) + details[:file_basename]
+      end
+
+      def cache_key(engine, api_file)
+        "#{engine}-#{api_file}"
+      end
+
+      def api_path(engines_path, engine)
+        raw_name = ActiveSupport::Inflector.underscore(engine.to_s)
+        File.join(engines_path, "#{raw_name}/app/api/#{raw_name}/api/")
+      end
+
+      def parse_ast(file_path)
+        source_code = File.read(file_path)
+        source = RuboCop::ProcessedSource.new(source_code, RUBY_VERSION.to_f)
+        source.ast
+      end
+
+      def extract_module_root(path)
+        # The AST for the whitelist definition looks like this:
+        #
+        # (:module,
+        #   (:const,
+        #     (:const, nil, :Trucking), :Api),
+        #   (:casgn, nil, :PUBLIC_SERVICES,
+        #     (:array,
+        #       (:const,
+        #         s(:const, nil, :Trucking), :CancelDeliveryOrderService),
+        #       (:const,
+        #         s(:const, nil, :Trucking), :FclFulfillmentDetailsService))
+        #
+        # Or, in the case of two separate whitelists:
+        #
+        # (:module,
+        #   (:const,
+        #     (:const, nil, :Trucking), :Api),
+        #   s(:begin,
+        #     s(:casgn, nil, :PUBLIC_SERVICES,
+        #       s(:send,
+        #         s(:array,
+        #           s(:const,
+        #             s(:const, nil, :Trucking), :CancelDeliveryOrderService),
+        #           s(:const,
+        #             s(:const, nil, :Trucking), :ContainerUseService))),
+        #     s(:casgn, nil, :PUBLIC_CONSTANTS,
+        #       s(:send,
+        #         s(:array,
+        #           s(:const,
+        #             s(:const, nil, :Trucking), :DeliveryStatuses),
+        #           s(:const,
+        #             s(:const, nil, :Trucking), :LoadTypes)), :freeze)))
+        #
+        # We want the :begin in the 2nd case, the :module in the 1st case.
+        module_node = parse_ast(path)
+        module_block_node = module_node&.children&.[](1)
+        if module_block_node&.begin_type?
+          module_block_node
+        else
+          module_node
+        end
+      end
+
+      def_node_matcher :whitelist_array, <<-PATTERN
+          (casgn nil? {:PUBLIC_MODULES :PUBLIC_SERVICES :PUBLIC_CONSTANTS :PUBLIC_TYPES} {$array (send $array ...)})
+      PATTERN
+
+      def_node_matcher :legacy_dependents_array, <<-PATTERN
+          (casgn nil? {:FILES_WITH_DIRECT_ACCESS} {$array (send $array ...)})
+      PATTERN
+
+      def extract_array(path, array_matcher)
+        list = []
+        root_node = extract_module_root(path)
+        root_node.children.each do |module_child|
+          array_node = send(array_matcher, module_child)
+          next if array_node.nil?
+
+          array_node.children.map do |item|
+            list << item.source
+          end
+        end
+        list
+      end
+    end
+  end
+end

data/lib/rubocop/flexport/version.rb

@@ -2,6 +2,6 @@
 
 module RuboCop
   module Flexport
-    VERSION = '0.2.0'
+    VERSION = '0.3.0'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rubocop-flexport
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Flexport Engineering
@@ -51,9 +51,11 @@ files:
 - bin/setup
 - config/default.yml
 - lib/rubocop-flexport.rb
+- lib/rubocop/cop/flexport/engine_api_boundary.rb
 - lib/rubocop/cop/flexport/global_model_access_from_engine.rb
 - lib/rubocop/cop/flexport/new_global_model.rb
 - lib/rubocop/cop/flexport_cops.rb
+- lib/rubocop/cop/mixin/engine_api.rb
 - lib/rubocop/flexport.rb
 - lib/rubocop/flexport/inject.rb
 - lib/rubocop/flexport/version.rb