package_protections 0.64.0

data/lib/package_protections/protection_interface.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+# typed: strict
+module PackageProtections
+  module ProtectionInterface
+    extend T::Sig
+    extend T::Helpers
+
+    abstract!
+
+    requires_ancestor { Kernel }
+
+    sig do
+      params(
+        protected_packages: T::Array[ProtectedPackage],
+        new_violations: T::Array[PerFileViolation]
+      ).returns(T::Array[Offense])
+    end
+    def get_offenses(protected_packages, new_violations)
+      [
+        # First we get all offenses for new violations
+        *get_offenses_for_new_violations(new_violations),
+        # Then we separately look at TODO lists and add violations if there are no issues
+        *get_offenses_for_existing_violations(protected_packages)
+      ].sort_by(&:message)
+    end
+
+    sig { abstract.params(behavior: ViolationBehavior, package: ParsePackwerk::Package).returns(T.nilable(String)) }
+    def unmet_preconditions_for_behavior(behavior, package); end
+
+    sig { params(behavior: ViolationBehavior, package: ParsePackwerk::Package).returns(T::Boolean) }
+    def supports_violation_behavior?(behavior, package)
+      unmet_preconditions_for_behavior(behavior, package).nil?
+    end
+
+    sig { returns(ViolationBehavior) }
+    def default_behavior
+      # The default behavior here is that we simply return the `fail_on_new` protection.
+      # In some cases, this protection may not actually be supported. For example, `OutgoingPrivacyProtection` raises if the user has `enforce_privacy: false`
+      # Error messages should provide enough clarity to either:
+      # A) Know which protection to explicitly set to fail_never
+      # B) Know how to change conditions to allow protection to be supported (i.e. set enforce dependencies to be true)
+      ViolationBehavior::FailOnNew
+    end
+
+    sig do
+      abstract.params(
+        new_violations: T::Array[PerFileViolation]
+      ).returns(T::Array[Offense])
+    end
+    def get_offenses_for_new_violations(new_violations); end
+
+    sig do
+      abstract.params(
+        protected_packages: T::Array[ProtectedPackage]
+      ).returns(T::Array[Offense])
+    end
+    def get_offenses_for_existing_violations(protected_packages); end
+
+    sig { abstract.returns(String) }
+    def identifier; end
+
+    sig { abstract.returns(String) }
+    def humanized_protection_name; end
+
+    sig { abstract.returns(String) }
+    def humanized_protection_description; end
+  end
+end

data/lib/package_protections/rubocop_protection_interface.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+# typed: strict
+module PackageProtections
+  module RubocopProtectionInterface
+    include ProtectionInterface
+    extend T::Sig
+    extend T::Helpers
+
+    abstract!
+
+    sig do
+      abstract
+        .params(packages: T::Array[ProtectedPackage])
+        .returns(T::Array[CopConfig])
+    end
+    def cop_configs(packages); end
+
+    sig do
+      params(package: ProtectedPackage).returns(T::Hash[T.untyped, T.untyped])
+    end
+    def custom_cop_config(package)
+      {}
+    end
+
+    class CopConfig < T::Struct
+      extend T::Sig
+      const :name, String
+      const :enabled, T::Boolean, default: true
+      const :include_paths, T::Array[String], default: []
+      const :exclude_paths, T::Array[String], default: []
+
+      sig { returns(String) }
+      def to_rubocop_yml_compatible_format
+        cop_config = { 'Enabled' => enabled }
+
+        if include_paths.any?
+          cop_config['Include'] = include_paths
+        end
+
+        if exclude_paths.any?
+          cop_config['Exclude'] = exclude_paths
+        end
+
+        { name => cop_config }.to_yaml.gsub("---\n", '')
+      end
+    end
+
+    sig do
+      override.params(
+        new_violations: T::Array[PerFileViolation]
+      ).returns(T::Array[Offense])
+    end
+    def get_offenses_for_new_violations(new_violations)
+      []
+    end
+
+    sig { void }
+    def self.bust_rubocop_todo_yml_cache
+      @rubocop_todo_yml = nil
+    end
+
+    sig { returns(T.untyped) }
+    def self.rubocop_todo_yml
+      @rubocop_todo_yml = T.let(@rubocop_todo_yml, T.untyped)
+      @rubocop_todo_yml ||= begin
+        todo_file = Pathname.new('.rubocop_todo.yml')
+        if todo_file.exist?
+          YAML.load_file(todo_file)
+        else
+          {}
+        end
+      end
+    end
+
+    private
+
+    sig { params(rule: String).returns(T::Set[String]) }
+    def exclude_for_rule(rule)
+      rule_config = RubocopProtectionInterface.rubocop_todo_yml[rule] || {}
+      Set.new(rule_config['Exclude'] || [])
+    end
+  end
+end

data/lib/package_protections/violation_behavior.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+# typed: strict
+module PackageProtections
+  class IncorrectPublicApiUsageError < StandardError; end
+
+  class ViolationBehavior < T::Enum
+    extend T::Sig
+
+    enums do
+      FailOnAny = new('fail_on_any')
+      FailOnNew = new('fail_on_new')
+      FailNever = new('fail_never')
+    end
+
+    sig { params(value: T.untyped).returns(ViolationBehavior) }
+    def self.from_raw_value(value)
+      ViolationBehavior.deserialize(value.to_s)
+    rescue KeyError
+      # Let's not encourage "unknown." That's mostly considered an internal value if nothing is specified.
+      acceptable_values = ViolationBehavior.values.map(&:serialize) - ['unknown']
+      raise IncorrectPublicApiUsageError.new("The metadata value #{value} is not a valid behavior. Double check your spelling! Acceptable values are #{acceptable_values}. See https://github.com/bigrails/package_protections#readme for more info") # rubocop:disable Style/RaiseArgs
+    end
+
+    sig { returns(T::Boolean) }
+    def fail_on_any?
+      case self
+      when FailOnAny then true
+      when FailOnNew then false
+      when FailNever then false
+      else
+        T.absurd(self)
+      end
+    end
+
+    sig { returns(T::Boolean) }
+    def enabled?
+      case self
+      when FailOnAny then true
+      when FailOnNew then true
+      when FailNever then false
+      else
+        T.absurd(self)
+      end
+    end
+
+    sig { returns(T::Boolean) }
+    def fail_on_new?
+      case self
+      when FailOnAny then false
+      when FailOnNew then true
+      when FailNever then false
+      else
+        T.absurd(self)
+      end
+    end
+
+    sig { returns(T::Boolean) }
+    def fail_never?
+      case self
+      when FailOnAny then false
+      when FailOnNew then false
+      when FailNever then true
+      else
+        T.absurd(self)
+      end
+    end
+  end
+end

data/lib/package_protections.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+# typed: strict
+require 'sorbet-runtime'
+require 'open3'
+require 'set'
+require 'parse_packwerk'
+require 'rubocop'
+require 'rubocop-sorbet'
+
+#
+# Welcome to PackageProtections!
+# See https://github.com/bigrails/package_protections#readme for more info
+#
+# This file is a reference for the available API to `package_protections`, but all implementation details are private
+# (which is why we delegate to `Private` for the actual implementation).
+#
+module PackageProtections
+  extend T::Sig
+
+  PROTECTIONS_TODO_YML = 'protections_todo.yml'
+  EXPECTED_PACK_DIRECTORIES = T.let(%w[packs packages gems components], T::Array[String])
+
+  # A protection identifier is just a string that identifies the name of the protection within a `package.yml`
+  Identifier = T.type_alias { String }
+
+  # This is currently the only handled exception that `PackageProtections` will throw.
+  class IncorrectPublicApiUsageError < StandardError; end
+
+  require 'package_protections/offense'
+  require 'package_protections/violation_behavior'
+  require 'package_protections/protected_package'
+  require 'package_protections/per_file_violation'
+  require 'package_protections/protection_interface'
+  require 'package_protections/rubocop_protection_interface'
+  require 'package_protections/private'
+
+  # Implementation of rubocop-based protections
+  require 'rubocop/cop/package_protections/namespaced_under_package_name'
+
+  #
+  # These are all of the concrete implementations of the `ProtectionInterface`.
+  # This list is added to when a new protection is created, but in the future,
+  # this list may be injected by the client.
+  #
+  sig { returns(T::Array[ProtectionInterface]) }
+  def self.all
+    [
+      Private::OutgoingDependencyProtection.new,
+      Private::IncomingPrivacyProtection.new,
+      Private::TypedApiProtection.new,
+      Private::MultipleNamespacesProtection.new,
+      Private::VisibilityProtection.new
+    ]
+  end
+
+  #
+  # This is a fast way to get a protection given an identifier
+  #
+  sig { params(identifier: Identifier).returns(ProtectionInterface) }
+  def self.with_identifier(identifier)
+    @map ||= T.let(@map, T.nilable(T::Hash[Identifier, ProtectionInterface]))
+    @map ||= all.map { |protection| [protection.identifier, protection] }.to_h
+    @map.fetch(identifier)
+  end
+
+  #
+  # This returns an array of a `Offense` which is how we represent the outcome of attempting to protect one or more packages,
+  # each of which is configured with different violation behaviors for each protection.
+  #
+  sig do
+    params(
+      packages: T::Array[ParsePackwerk::Package],
+      new_violations: T::Array[PerFileViolation]
+    ).returns(T::Array[Offense])
+  end
+  def self.get_offenses(packages:, new_violations:)
+    Private.get_offenses(
+      packages: packages,
+      new_violations: new_violations
+    ).compact
+  end
+
+  #
+  # PackageProtections.set_defaults! sets any unset protections to their default enforcement
+  #
+  sig do
+    params(
+      packages: T::Array[ParsePackwerk::Package],
+      protection_identifiers: T::Array[String],
+      verbose: T::Boolean
+    ).void
+  end
+  def self.set_defaults!(packages, protection_identifiers: PackageProtections.all.map(&:identifier), verbose: true)
+    Private.set_defaults!(packages, protection_identifiers: protection_identifiers, verbose: verbose)
+  end
+
+  # Why do we use Bundler.root here?
+  # The reason is that this function is evaluated in `.client_rubocop.yml`, so when rubocop evaluates the
+  # YML and parses the ERB, the working directory is inside this gem. We need to make sure it's at the root of the
+  # application so that we can find all of the packwerk packages.
+  # We use Bundler.root to get the root because:
+  # A) We expect it to be reliable
+  # B) We expect the client to be running bundle exec rubocop, which is typically done at the root, and also means
+  # the client already has this dependency.
+  sig { params(root_pathname: Pathname).returns(String) }
+  def self.rubocop_yml(root_pathname: Bundler.root)
+    Private.rubocop_yml(root_pathname: root_pathname)
+  end
+
+  #
+  # Do not use this method -- it's meant to be used by Rubocop cops to get directory-specific
+  # parameters without needing to have directory-specific .rubocop.yml files.
+  #
+  sig { params(identifier: Identifier).returns(T::Hash[T.untyped, T.untyped]) }
+  def self.private_cop_config(identifier)
+    Private.private_cop_config(identifier)
+  end
+
+  sig do
+    params(
+      package_names: T::Array[String],
+      all_packages: T::Array[ParsePackwerk::Package]
+    ).returns(T::Array[ParsePackwerk::Package])
+  end
+  def self.packages_for_names(package_names, all_packages)
+    Private.packages_for_names(package_names, all_packages)
+  end
+
+  sig { void }
+  def self.bust_cache!
+    Private.bust_cache!
+    RubocopProtectionInterface.bust_rubocop_todo_yml_cache
+  end
+end

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

@@ -0,0 +1,108 @@
+# typed: ignore
+
+# For String#camelize
+require 'active_support/core_ext/string/inflections'
+
+module RuboCop
+  module Cop
+    module PackageProtections
+      class NamespacedUnderPackageName < Base
+        include RangeHelp
+
+        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 in `app`
+          return if !relative_filename.include?('app/')
+
+          match = relative_filename.match(%r{((#{::PackageProtections::EXPECTED_PACK_DIRECTORIES.join("|")})/.*?)/})
+          package_name = match && match[1]
+
+          return if package_name.nil?
+
+          return if relative_filepath.extname != '.rb'
+
+          # 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.
+          package_last_name = package_name.split('/').last
+          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, relative_filepath, package_name)
+          allowed_namespaces = get_allowed_namespaces(package_name)
+          if allowed_namespaces.include?(actual_namespace)
+            # No problem!
+          elsif allowed_namespaces.count == 1
+            single_allowed_namespace = allowed_namespaces.first
+            if relative_filepath.to_s.include?('app/')
+              app_or_lib = 'app'
+            elsif relative_filepath.to_s.include?('lib/')
+              app_or_lib = 'lib'
+            end
+
+            absolute_desired_path = root_pathname.join(package_name, app_or_lib, T.must(autoload_folder_name), single_allowed_namespace.underscore, remaining_file_path)
+
+            relative_desired_path = absolute_desired_path.relative_path_from(root_pathname)
+
+            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: package_last_name.camelize,
+                expected_path: relative_desired_path
+              )
+            )
+          else
+            add_offense(
+              source_range(processed_source.buffer, 1, 0),
+              message: format(
+                '`%<package_name>s` prevents modules/classes that are not submodules of one of the allowed namespaces in `%<package_yml>s`. See https://go/packwerk_cheatsheet_namespaces for more info.',
+                package_name: package_name,
+                package_yml: "#{package_name}/package.yml"
+              )
+            )
+          end
+        end
+
+        private
+
+        def get_allowed_namespaces(package_name)
+          cop_config = ::PackageProtections.private_cop_config('prevent_this_package_from_creating_other_namespaces')
+          allowed_global_namespaces = cop_config[package_name]['GlobalNamespaces'] || [package_name.split('/').last.camelize]
+          Set.new(allowed_global_namespaces)
+        end
+
+        def get_actual_namespace(remaining_file_path, relative_filepath, 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
+          remaining_file_path.split('/').first.gsub('.rb', '').camelize
+        end
+
+        def root_pathname
+          Pathname.pwd
+        end
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,220 @@
+--- !ruby/object:Gem::Specification
+name: package_protections
+version: !ruby/object:Gem::Version
+  version: 0.64.0
+platform: ruby
+authors:
+- Gusto Engineers
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2022-05-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: parse_packwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-sorbet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sorbet-runtime
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sorbet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: tapioca
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Package protections for Rails apps
+email:
+- stephan.hagemann@gusto.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- config/default.yml
+- lib/package_protections.rb
+- lib/package_protections/offense.rb
+- lib/package_protections/per_file_violation.rb
+- lib/package_protections/private.rb
+- lib/package_protections/private/colorized_string.rb
+- lib/package_protections/private/incoming_privacy_protection.rb
+- lib/package_protections/private/metadata_modifiers.rb
+- lib/package_protections/private/multiple_namespaces_protection.rb
+- lib/package_protections/private/outgoing_dependency_protection.rb
+- lib/package_protections/private/output.rb
+- lib/package_protections/private/typed_api_protection.rb
+- lib/package_protections/private/visibility_protection.rb
+- lib/package_protections/protected_package.rb
+- lib/package_protections/protection_interface.rb
+- lib/package_protections/rubocop_protection_interface.rb
+- lib/package_protections/violation_behavior.rb
+- lib/rubocop/cop/package_protections/namespaced_under_package_name.rb
+homepage: https://github.com/bigrails/package_protections
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/bigrails/package_protections
+  source_code_uri: https://github.com/bigrails/parse_packwerk
+  changelog_uri: https://github.com/bigrails/parse_packwerk/releases
+  allowed_push_host: https://rubygems.org
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.5.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.7
+signing_key: 
+specification_version: 4
+summary: Package protections for Rails apps
+test_files: []