rubocop-packs 0.0.7

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: bfc93294dd3f42e1dece0b632adba1a4a9ac811d0328c682dd121f2f11063d98
+  data.tar.gz: df7a631fa820a30b672461e106882e7221555ddd3f64ba690dd8f7407d172ca4
+SHA512:
+  metadata.gz: ff8d5fbd4ab6233223b705ab097bed58aa9e45139e148c084c071a299720a12759fe2173ba6f557d5794b7e097c5dbc0ef87db3744bd47903662721fb4a8831e
+  data.tar.gz: cf7e59a3a2aa75057cee35ed0d5938b0c3131eff0d5c9657d9705833f26bff636ebc2d2ecf21fe69d04a49121e4772fa32457fe70225345587b3baaca77e1350

data/README.md

@@ -0,0 +1,84 @@
+# rubocop-packs
+
+A collection of Rubocop rules for modularizing ruby applications that conform to the `packs` standard.
+
+## Installation
+
+Just install the `rubocop-packs` gem
+
+```sh
+gem install rubocop-packs
+```
+or, if you use `Bundler`, add this line your application's `Gemfile`:
+
+```ruby
+gem 'rubocop-packs', require: false
+```
+
+## Usage
+
+You need to tell RuboCop to load the Packs extension. There are three ways to do this:
+
+### RuboCop configuration file
+
+Put this into your `.rubocop.yml`:
+
+```yaml
+require: rubocop-packs
+```
+
+Alternatively, use the following array notation when specifying multiple extensions:
+
+```yaml
+require:
+  - rubocop-other-extension
+  - rubocop-packs
+```
+
+Now you can run `rubocop` and it will automatically load the RuboCop Packs cops together with the standard cops.
+
+### Command line
+
+```sh
+rubocop --require rubocop-packs
+```
+
+### Rake task
+
+```ruby
+RuboCop::RakeTask.new do |task|
+  task.requires << 'rubocop-packs'
+end
+```
+
+## The Cops
+All cops are located under [`lib/rubocop/cop/packs`](lib/rubocop/cop/packs), and contain examples/documentation.
+
+In your `.rubocop.yml`, you may treat the Packs cops just like any other cop. For example:
+
+```yaml
+Packs/NamespacedUnderPackageName:
+  Exclude:
+    - lib/example.rb
+```
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/rubyatscale/rubocop-packs. 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[Packs/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-packs/blob/main/LICENSE.txt).

data/config/default.yml

@@ -0,0 +1,16 @@
+Packs/ClassMethodsAsPublicApis:
+  Enabled: true
+  AcceptableParentClasses:
+    - T::Enum
+    - T::Struct
+    - Struct
+    - OpenStruct
+
+Packs/NamespacedUnderPackageName:
+  Enabled: false
+
+Packs/TypedPublicApi:
+  Enabled: false
+
+Packs/RequireDocumentedPublicApis:
+  Enabled: false

data/lib/rubocop/cop/packs/class_methods_as_public_apis.rb

@@ -0,0 +1,71 @@
+# typed: strict
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Packs
+      # This cop states that public API should live on class methods, which are more easily statically analyzable,
+      # searchable, and typically hold less state.
+      #
+      # @example
+      #
+      #   # bad
+      #   # packs/foo/app/public/foo.rb
+      #   module Foo
+      #     def blah
+      #     end
+      #   end
+      #
+      #   # good
+      #   # packs/foo/app/public/foo.rb
+      #   module Foo
+      #     def self.blah
+      #     end
+      #   end
+      #
+      # @example AcceptableParentClasses: [T::Enum, T::Struct, Struct, OpenStruct] (default)
+      #   You can define `AcceptableParentClasses` which are a list of classes that, if inherited from, non-class methods are permitted.
+      #   This is useful when value objects are a part of your public API.
+      #
+      #   # good
+      #   # packs/foo/app/public/foo.rb
+      #   class Foo < T::Enum
+      #     const :blah
+      #   end
+      #
+      class ClassMethodsAsPublicApis < Base
+        extend T::Sig
+
+        sig { returns(T::Boolean) }
+        def support_autocorrect?
+          false
+        end
+
+        sig { params(node: T.untyped).void }
+        def on_def(node)
+          # This cop only applies for ruby files in `app/public`
+          return if !processed_source.file_path.include?('app/public')
+
+          # Looked at https://www.rubydoc.info/gems/rubocop/RuboCop/Cop/Lint/MissingSuper source code as inspiration for htis part.
+          class_node = node.each_ancestor(:class).first
+          module_node = node.each_ancestor(:module).first
+          parent_class = class_node&.parent_class || module_node&.parent
+
+          acceptable_parent_classes = cop_config['AcceptableParentClasses'] || []
+
+          # Used this PR as inspiration to check if we're within a `class << self` block
+          uses_implicit_static_methods = node.each_ancestor(:sclass).first&.identifier&.source == 'self'
+          class_is_allowed_to_have_instance_methods = acceptable_parent_classes.include?(parent_class&.const_name)
+          return if uses_implicit_static_methods || class_is_allowed_to_have_instance_methods
+
+          add_offense(
+            node.source_range,
+            message: format(
+              'Top-level files in the public/ folder may only define class methods.'
+            )
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,110 @@
+# typed: strict
+
+module RuboCop
+  module Cop
+    module Packs
+      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/packs/namespaced_under_package_name.rb

@@ -0,0 +1,119 @@
+# typed: strict
+
+# For String#camelize
+require 'active_support/core_ext/string/inflections'
+require 'rubocop/cop/packs/namespaced_under_package_name/desired_zeitwerk_api'
+
+module RuboCop
+  module Cop
+    module Packs
+      # 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/packs/require_documented_public_apis.rb

@@ -0,0 +1,34 @@
+# typed: strict
+
+module RuboCop
+  module Cop
+    module Packs
+      class RequireDocumentedPublicApis < Style::DocumentationMethod
+        extend T::Sig
+
+        sig { returns(T::Boolean) }
+        def support_autocorrect?
+          false
+        end
+
+        sig { params(node: T.untyped).void }
+        def check(node)
+          # This cop only applies for ruby files in `app/public`
+          return if !processed_source.file_path.include?('app/public')
+          return if non_public?(node) && !require_for_non_public_methods?
+
+          left_sibling = node.left_sibling
+          left_sibling_is_sig = left_sibling && (left_sibling.source.include?('sig do') || left_sibling.source.include?('sig {'))
+          # Is there a better way to check if the left sibling is a sorbet signature? Probably!
+          if left_sibling_is_sig
+            return if documentation_comment?(node.left_sibling)
+          elsif documentation_comment?(node)
+            return
+          end
+
+          add_offense(node)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,39 @@
+# typed: strict
+
+require 'rubocop-sorbet'
+
+module RuboCop
+  module Cop
+    module Packs
+      # 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/packs/inject.rb

@@ -0,0 +1,24 @@
+# typed: strict
+# frozen_string_literal: true
+
+# The original code is from https://github.com/rubocop/rubocop-rspec/blob/master/lib/rubocop/rspec/inject.rb
+# See https://github.com/rubocop/rubocop-rspec/blob/master/MIT-LICENSE.md
+module RuboCop
+  module Packs
+    # 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)
+        config = Config.new(hash, path).tap(&:make_excludes_absolute)
+        puts "configuration from #{path}" if ConfigLoader.debug?
+        config = ConfigLoader.merge_with_default(config, path)
+        ConfigLoader.instance_variable_set(:@default_configuration, config)
+      end
+    end
+  end
+end

data/lib/rubocop/packs/private.rb

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

data/lib/rubocop/packs.rb

@@ -0,0 +1,18 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'rubocop/packs/private'
+
+module RuboCop
+  module Packs
+    class Error < StandardError; end
+    extend T::Sig
+
+    # Your code goes here...
+    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-packs.rb

@@ -0,0 +1,15 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'rubocop'
+require 'parse_packwerk'
+
+require_relative 'rubocop/packs'
+require_relative 'rubocop/packs/inject'
+
+require 'rubocop/cop/packs/namespaced_under_package_name'
+require 'rubocop/cop/packs/typed_public_api'
+require 'rubocop/cop/packs/class_methods_as_public_apis'
+require 'rubocop/cop/packs/require_documented_public_apis'
+
+RuboCop::Packs::Inject.defaults!

data/sorbet/config

@@ -0,0 +1,3 @@
+--dir
+.
+--ignore=/vendor/bundle