rubocop-modularization 0.0.1 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4b0a6cf1f19e21271cc4aabe132a9fae31f38b15d7a2ed6602a29a15de72fde7
-  data.tar.gz: d2e6d37536be643977a275a62d77e0c01ec86b20a57c9826d60d71128b628473
+  metadata.gz: a7be2735c3d928d9c4ccf2643f2d07c533926ded38120b0d50e825d021065d92
+  data.tar.gz: dc19628fa31d58ced5e4b93af213d31f475c23669da692722b41c3c12140fc71
 SHA512:
-  metadata.gz: 0d94c4ee844d369e8b9a7ecc8cc1f0bab5f070cb7dbd413a5e3a14bb37cb4a03c88b743316e0316b2aed6ec2290d1f0c8d086253c1dbd00c625e06705e384d6f
-  data.tar.gz: 0f11f26c9d0282dbe9b0b40738a66430b054b62a6c27d6e251eb3fa4ee8077a1766d9be549410ac9682dd223c055d947916802a51f32d10c2ca6ffaf45b1b435
+  metadata.gz: 55916f5fdcf893b864f41d69b69cb595f2b32427164e6cfd9f32cd2859d8ff6b2db012c7fc4a14a665b600efae8645a73bdab8f26f8b2455c0e4b461e21bcdb0
+  data.tar.gz: 5a558caa1855c9aeb2317c574d9c6983fe6ca35ef9a1fb34af4d285cc432810961273928cf628293452102dd1ba0d0c5d817ab6feb3fe6c833a49485fec1aa5f

data/README.md

@@ -1,5 +1,84 @@
 # rubocop-modularization
 
-To finish off using this template:
-1) Replace all instances of `rubocop-modularization` and `MyGem` with your gem's name.
-2) Rename all files and folders from `rubocop-modularization` to your gem's name.
+A collection of Rubocop rules for modularization..
+
+## Installation
+
+Just install the `rubocop-modularization` gem
+
+```sh
+gem install rubocop-modularization
+```
+or, if you use `Bundler`, add this line your application's `Gemfile`:
+
+```ruby
+gem 'rubocop-modularization', require: false
+```
+
+## Usage
+
+You need to tell RuboCop to load the Modularization extension. There are three ways to do this:
+
+### RuboCop configuration file
+
+Put this into your `.rubocop.yml`:
+
+```yaml
+require: rubocop-modularization
+```
+
+Alternatively, use the following array notation when specifying multiple extensions:
+
+```yaml
+require:
+  - rubocop-other-extension
+  - rubocop-modularization
+```
+
+Now you can run `rubocop` and it will automatically load the RuboCop Modularization cops together with the standard cops.
+
+### Command line
+
+```sh
+rubocop --require rubocop-modularization
+```
+
+### Rake task
+
+```ruby
+RuboCop::RakeTask.new do |task|
+  task.requires << 'rubocop-modularization'
+end
+```
+
+## The Cops
+All cops are located under [`lib/rubocop/cop/modularization`](lib/rubocop/cop/modularization), and contain examples/documentation.
+
+In your `.rubocop.yml`, you may treat the Modularization cops just like any other cop. For example:
+
+```yaml
+Modularization/NamespacedUnderPackageName:
+  Exclude:
+    - lib/example.rb
+```
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/rubyatscale/rubocop-modularization. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Code Of Conduct](CODE_OF_CONDUCT.MD).
+
+To contribute a new cop, please use the supplied generator like this:
+
+```sh
+bundle exec rake new_cop[Modularization/NewCopName]
+```
+
+which will create a skeleton cop, a skeleton spec, an entry in the default config file and will require the new cop so that it is properly exported from the gem.
+
+Don't forget to update the documentation with:
+
+```sh
+VERIFYING_DOCUMENTATION=1 bundle exec rake generate_cops_documentation
+```
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://github.com/Shopify/rubocop-modularization/blob/main/LICENSE.txt).

data/config/default.yml

@@ -0,0 +1,5 @@
+Modularization/NamespacedUnderPackageName:
+  Enabled: false
+
+Modularization/TypedPublicApi:
+  Enabled: false

data/lib/rubocop/cop/modularization/namespaced_under_package_name/desired_zeitwerk_api.rb

@@ -0,0 +1,110 @@
+# typed: strict
+
+module RuboCop
+  module Cop
+    module Modularization
+      class NamespacedUnderPackageName < Base
+        #
+        # This is a private class that represents API that we would prefer to be available somehow in Zeitwerk.
+        #
+        class DesiredZeitwerkApi
+          extend T::Sig
+
+          class NamespaceContext < T::Struct
+            const :current_namespace, String
+            const :expected_namespace, String
+            const :expected_filepath, String
+          end
+
+          #
+          # For now, this API includes `package_for_path`
+          # If this were truly zeitwerk API, it wouldn't include any mention of packs and it would likely not need the package at all
+          # Since it could get the actual namespace without knowing anything about packs.
+          # However, we would need to pass to it the desired namespace based on the pack name for it to be able to suggest
+          # a desired filepath.
+          # Likely this means that our own cop should determine the desired namespace and pass that in
+          # and this can determine actual namespace and how to get to expected.
+          #
+          sig { params(relative_filename: String, package_for_path: ParsePackwerk::Package).returns(T.nilable(NamespaceContext)) }
+          def for_file(relative_filename, package_for_path)
+            package_name = package_for_path.name
+
+            # Zeitwerk establishes a standard convention by which namespaces are defined.
+            # The package protections namespace checker is coupled to a specific assumption about how auto-loading works.
+            #
+            # Namely, we expect the following autoload paths: `packs/**/app/**/`
+            # Examples:
+            # 1) `packs/package_1/app/public/package_1/my_constant.rb` produces constant `Package1::MyConstant`
+            # 2) `packs/package_1/app/services/package_1/my_service.rb` produces constant `Package1::MyService`
+            # 3) `packs/package_1/app/services/package_1.rb` produces constant `Package1`
+            # 4) `packs/package_1/app/public/package_1.rb` produces constant `Package1`
+            #
+            # Described another way, we expect any part of the directory labeled NAMESPACE to establish a portion of the fully qualified runtime constant:
+            # `packs/**/app/**/NAMESPACE1/NAMESPACE2/[etc]`
+            #
+            # Therefore, for our implementation, we substitute out the non-namespace producing portions of the filename to count the number of namespaces.
+            # Note this will *not work* properly in applications that have different assumptions about autoloading.
+
+            path_without_package_base = relative_filename.gsub(%r{#{package_name}/app/}, '')
+            if path_without_package_base.include?('concerns')
+              autoload_folder_name = path_without_package_base.split('/').first(2).join('/')
+            else
+              autoload_folder_name = path_without_package_base.split('/').first
+            end
+
+            remaining_file_path = path_without_package_base.gsub(%r{\A#{autoload_folder_name}/}, '')
+            actual_namespace = get_actual_namespace(remaining_file_path, package_name)
+
+            if relative_filename.include?('app/')
+              app_or_lib = 'app'
+            elsif relative_filename.include?('lib/')
+              app_or_lib = 'lib'
+            end
+
+            absolute_desired_path = root_pathname.join(
+              package_name,
+              T.must(app_or_lib),
+              T.must(autoload_folder_name),
+              get_package_last_name(package_for_path),
+              remaining_file_path
+            )
+
+            relative_desired_path = absolute_desired_path.relative_path_from(root_pathname)
+
+            NamespaceContext.new(
+              current_namespace: actual_namespace,
+              expected_namespace: get_pack_based_namespace(package_for_path),
+              expected_filepath: relative_desired_path.to_s
+            )
+          end
+
+          sig { params(pack: ParsePackwerk::Package).returns(String) }
+          def get_pack_based_namespace(pack)
+            get_package_last_name(pack).camelize
+          end
+
+          private
+
+          sig { returns(Pathname) }
+          def root_pathname
+            Pathname.pwd
+          end
+
+          sig { params(pack: ParsePackwerk::Package).returns(String) }
+          def get_package_last_name(pack)
+            T.must(pack.name.split('/').last)
+          end
+
+          sig { params(remaining_file_path: String, package_name: String).returns(String) }
+          def get_actual_namespace(remaining_file_path, package_name)
+            # If the remaining file path is a ruby file (not a directory), then it establishes a global namespace
+            # Otherwise, per Zeitwerk's conventions as listed above, its a directory that establishes another global namespace
+            T.must(remaining_file_path.split('/').first).gsub('.rb', '').camelize
+          end
+        end
+
+        private_constant :DesiredZeitwerkApi
+      end
+    end
+  end
+end

data/lib/rubocop/cop/modularization/namespaced_under_package_name.rb

@@ -0,0 +1,119 @@
+# typed: strict
+
+# For String#camelize
+require 'active_support/core_ext/string/inflections'
+require 'rubocop/cop/modularization/namespaced_under_package_name/desired_zeitwerk_api'
+
+module RuboCop
+  module Cop
+    module Modularization
+      # This cop helps ensure that each pack exposes one namespace.
+      #
+      # @example
+      #
+      #   # bad
+      #   # packs/foo/app/services/blah/bar.rb
+      #   class Blah::Bar; end
+      #
+      #   # good
+      #   # packs/foo/app/services/foo/blah/bar.rb
+      #   class Foo::Blah::Bar; end
+      #
+      class NamespacedUnderPackageName < Base
+        extend T::Sig
+
+        include RangeHelp
+
+        sig { void }
+        def on_new_investigation
+          absolute_filepath = Pathname.new(processed_source.file_path)
+          relative_filepath = absolute_filepath.relative_path_from(Pathname.pwd)
+          relative_filename = relative_filepath.to_s
+
+          # This cop only works for files ruby files in `app`
+          return if !relative_filename.include?('app/') || relative_filepath.extname != '.rb'
+
+          relative_filename = relative_filepath.to_s
+          package_for_path = ParsePackwerk.package_from_path(relative_filename)
+          return if package_for_path.nil?
+
+          namespace_context = desired_zeitwerk_api.for_file(relative_filename, package_for_path)
+          return if namespace_context.nil?
+
+          allowed_global_namespaces = Set.new([
+                                                namespace_context.expected_namespace,
+                                                *cop_config['GloballyPermittedNamespaces']
+                                              ])
+
+          package_name = package_for_path.name
+          actual_namespace = namespace_context.current_namespace
+
+          if allowed_global_namespaces.include?(actual_namespace)
+            # No problem!
+          else
+            package_enforces_namespaces = cop_config['IncludePacks'].include?(package_for_path.name)
+            expected_namespace = namespace_context.expected_namespace
+            relative_desired_path = namespace_context.expected_filepath
+            pack_owning_this_namespace = namespaces_to_packs[actual_namespace]
+
+            if package_enforces_namespaces
+              add_offense(
+                source_range(processed_source.buffer, 1, 0),
+                message: format(
+                  '`%<package_name>s` prevents modules/classes that are not submodules of the package namespace. Should be namespaced under `%<expected_namespace>s` with path `%<expected_path>s`. See https://go/packwerk_cheatsheet_namespaces for more info.',
+                  package_name: package_name,
+                  expected_namespace: expected_namespace,
+                  expected_path: relative_desired_path
+                )
+              )
+            elsif pack_owning_this_namespace
+              add_offense(
+                source_range(processed_source.buffer, 1, 0),
+                message: format(
+                  '`%<pack_owning_this_namespace>s` prevents other packs from sitting in the `%<actual_namespace>s` namespace. This should be namespaced under `%<expected_namespace>s` with path `%<expected_path>s`. See https://go/packwerk_cheatsheet_namespaces for more info.',
+                  package_name: package_name,
+                  pack_owning_this_namespace: pack_owning_this_namespace,
+                  expected_namespace: expected_namespace,
+                  actual_namespace: actual_namespace,
+                  expected_path: relative_desired_path
+                )
+              )
+            end
+          end
+        end
+
+        # In the future, we'd love this to support auto-correct.
+        # Perhaps by automatically renamespacing the file and changing its location?
+        sig { returns(T::Boolean) }
+        def support_autocorrect?
+          false
+        end
+
+        private
+
+        sig { returns(DesiredZeitwerkApi) }
+        def desired_zeitwerk_api
+          @desired_zeitwerk_api ||= T.let(nil, T.nilable(DesiredZeitwerkApi))
+          @desired_zeitwerk_api ||= DesiredZeitwerkApi.new
+        end
+
+        sig { returns(T::Hash[String, String]) }
+        def namespaces_to_packs
+          @namespaces_to_packs = T.let(nil, T.nilable(T::Hash[String, String]))
+          @namespaces_to_packs ||= begin
+            all_packs_enforcing_namespaces = ParsePackwerk.all.select do |p|
+              cop_config['IncludePacks'].include?(p.name)
+            end
+
+            namespaces_to_packs = {}
+            all_packs_enforcing_namespaces.each do |package|
+              namespaces_to_packs[desired_zeitwerk_api.get_pack_based_namespace(package)] = package.name
+            end
+
+            namespaces_to_packs
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/modularization/typed_public_api.rb

@@ -0,0 +1,39 @@
+# typed: strict
+
+require 'rubocop-sorbet'
+
+module RuboCop
+  module Cop
+    module Modularization
+      # This cop helps ensure that each pack's public API is strictly typed, enforcing strong boundaries.
+      #
+      # @example
+      #
+      #   # bad
+      #   # packs/foo/app/public/foo.rb
+      #   # typed: false
+      #   module Foo; end
+      #
+      #   # good
+      #   # packs/foo/app/public/foo.rb
+      #   # typed: strict
+      #   module Foo; end
+      #
+      class TypedPublicApi < Sorbet::StrictSigil
+        #
+        # This inherits from `Sorbet::StrictSigil` and doesn't change any behavior of it.
+        # The only reason we do this is so that configuration for this cop can live under a different cop namespace.
+        # This prevents this cop's configuration from clashing with other configurations for the same cop.
+        # A concrete example of this would be if a user is using this package protection to make sure public APIs are typed,
+        # and separately the application as a whole requiring strict typing in certain parts of the application.
+        #
+        # To prevent problems associated with needing to manage identical configurations for the same cop, we simply call it
+        # something else in the context of this protection.
+        #
+        # We can apply this same pattern if we want to use other cops in the context of package protections and prevent clashing.
+        #
+        extend T::Sig
+      end
+    end
+  end
+end

data/lib/rubocop/cop/modularization_cops.rb

@@ -1 +1,2 @@
+# typed: strict
 # frozen_string_literal: true

data/lib/rubocop/modularization/inject.rb

@@ -1,3 +1,4 @@
+# typed: strict
 # frozen_string_literal: true
 
 # The original code is from https://github.com/rubocop/rubocop-rspec/blob/master/lib/rubocop/rspec/inject.rb
@@ -7,6 +8,9 @@ module RuboCop
     # Because RuboCop doesn't yet support plugins, we have to monkey patch in a
     # bit of our configuration.
     module Inject
+      extend T::Sig
+
+      sig { void }
       def self.defaults!
         path = CONFIG_DEFAULT.to_s
         hash = ConfigLoader.send(:load_yaml_configuration, path)

data/lib/rubocop/modularization/private.rb

@@ -0,0 +1,11 @@
+# typed: strict
+# frozen_string_literal: true
+
+module RuboCop
+  module Modularization
+    module Private
+    end
+
+    private_constant :Private
+  end
+end

data/lib/rubocop/modularization.rb

@@ -1,14 +1,18 @@
+# typed: strict
 # frozen_string_literal: true
 
+require 'rubocop/modularization/private'
+
 module RuboCop
   module Modularization
     class Error < StandardError; end
+    extend T::Sig
+
     # Your code goes here...
-    PROJECT_ROOT   = Pathname.new(__dir__).parent.parent.expand_path.freeze
-    CONFIG_DEFAULT = PROJECT_ROOT.join('config', 'default.yml').freeze
-    CONFIG         = YAML.safe_load(CONFIG_DEFAULT.read).freeze
+    PROJECT_ROOT   = T.let(Pathname.new(__dir__).parent.parent.expand_path.freeze, Pathname)
+    CONFIG_DEFAULT = T.let(PROJECT_ROOT.join('config', 'default.yml').freeze, Pathname)
+    CONFIG         = T.let(YAML.safe_load(CONFIG_DEFAULT.read).freeze, T.untyped)
 
     private_constant(:CONFIG_DEFAULT, :PROJECT_ROOT)
   end
 end
-

data/lib/rubocop-modularization.rb

@@ -1,10 +1,13 @@
+# typed: strict
 # frozen_string_literal: true
 
 require 'rubocop'
+require 'parse_packwerk'
 
 require_relative 'rubocop/modularization'
 require_relative 'rubocop/modularization/inject'
 
-RuboCop::Modularization::Inject.defaults!
+require 'rubocop/cop/modularization/namespaced_under_package_name'
+require 'rubocop/cop/modularization/typed_public_api'
 
-require_relative 'rubocop/cop/modularization_cops'
+RuboCop::Modularization::Inject.defaults!