package_protections 0.64.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f1b60522d3be3ff25aaab73a4c0e6d4d0585657663352b9c353d6df3307287c4
+  data.tar.gz: 8b57faaea71bfb8b64f842b7e2ec40cdc313bc2c674243a698c9dc7bcbc21b56
+SHA512:
+  metadata.gz: e35ac2ae85c9459f3e480ba9939bf7e5db0902049c3643620e3ba2478a443c87dfe1ac1c9029254d7f616ac0d4821df3d07625e332a431349ff4860d5f46e64e
+  data.tar.gz: c90972ea3fbf86c36ea1492948fa56cd42e2b38731f6e9410c69296286d43310e7104413ccb20206392e1546e3b82c23ea25ba16defe09960718b7dadb63189f

data/README.md

@@ -0,0 +1,149 @@
+# PackageProtections
+
+This gem helps us use Packwerk and Rubocop to create well-packaged code.
+The intent of this gem is two fold:
+1) Provide a coherent modularization interface, where each `package.yml` is the main place you go to configure modularization checks.
+2) Create hard-checks for packwerk and rubocop. Packwerk and rubocop support gradual adoption, but they don't support the ability to block adding to the TODO list once a package has fully adhered to a rule.
+
+This gem ships with the following checks
+1) Your package is not introducing dependencies that are not intended (via `packwerk` `enforce_dependencies`)
+2) Other packages are not using the private API of your package (via `packwerk` `enforce_privacy`)
+3) Your package has a typed public API (via the `rubocop` `Sorbet/StrictSigil` cop)
+4) Your package only creates a single namespace (via the `rubocop` `PackageProtections/NamespacedUnderPackageName` cop)
+4) Your package is only visible to a select number of packages (via the `packwerk` `enforce_privacy` cop)
+
+## Initial Configuration
+Package protections first requires that your application is using [`packwerk`](https://github.com/Shopify/packwerk), [`rubocop`](https://github.com/rubocop/rubocop), and [`rubocop-sorbet`](https://github.com/Shopify/rubocop-sorbet). Follow the regular setup instructions for those tools before proceeding.
+
+Some of our package protections are implemented by rubocop, with their interface in `package.yml` files.
+For initial configuration in a new application, you need to tell RuboCop to load the package protections extension:
+```yml
+# `.rubocop.yml`
+inherit_gem:
+  package_protections:
+    - config/default.yml
+
+require:
+  - package_protections
+```
+
+## Usage
+Today, `PackageProtections` has several built-in protections that you can configure to protect your package.
+
+*By default, all protections are set to fail on new violations. Users need to specifically "opt out" if they do not want a protection.
+We want this because we want default behavior to be our vision for well-protected packages, and deviations from the ideal vision should require explicit user action.*
+Most protections set their default to `fail_on_new` instead of `fail_on_any` because we want to make it easy for users to split up packages into other ones and improve boundaries incrementally. We recommend packages for totally greenfield features use the `fail_on_any` behavior.
+
+Lastly, note that unless a protection's default behavior is `fail_never`, the protection must explicitly be set.
+
+To change the behavior for these protections, add the correct YAML key under `metadata.protections`. See `Example Usage` below for an example.
+
+### `prevent_this_package_from_violating_its_stated_dependencies`
+*This is only available if your package has `enforce_dependencies` set to `true`!*
+This protection ensures that your package does not use API from packages that are not listed under `dependencies` in `package.yml`. This helps make sure you manage your dependencies.
+
+### `prevent_other_packages_from_using_this_packages_internals`
+*This is only available if your package has `enforce_privacy` set to `true`!*
+This protection ensures that OTHER packages do not use the private API of your package. This helps ensure that clients are using your code the way you intend.
+
+### `prevent_this_package_from_exposing_an_untyped_api`
+This protection ensures that all files within `app/public` are typed at level `strict`, which means that every file must have a type signature. See https://sorbet.org/docs/static#file-level-granularity-strictness-levels for more information on typed strictness levels. Make sure to generate a TODO list if you want to use the `fail_on_new` violation behavior. See more information on generating a TODO list in the `fail_on_new` subsection under violation behaviors.
+
+### `prevent_this_package_from_creating_other_namespaces`
+*This is only available if your package is in `./packs`, `./gems`, `./components`, or `./packages`.*
+This helps ensure that your package is only creating one namespace (based on folder hierarchy). This helps organize the public API of your pack into one place.
+This protection only looks at files in `packs/your_pack/app` (it ignores spec files).
+This protection is implemented via Rubocop -- expect to see results for this when running `rubocop` however you normally do. To add to the TODO list, add to `.rubocop_todo.yml`
+Lastly – this protection can be configured by setting `global_namespaces` within the `package.yml`, e.g.:
+```
+enforce_privacy: true
+enforce_dependencies: true
+metadata:
+  protections:
+    # ... nothing changes here
+  global_namespaces:
+    - MyNamespace
+    - MyOtherNamespace
+    - MyThirdNamespace
+    # ... etc.
+```
+
+It's encouraged to limit the number of global namespaces your package exposes, and to make sure your global namespaces are as specific to your domain as possible.
+
+### `prevent_other_packages_from_using_this_package_without_explicit_visibility`
+*This is only available if your package has `enforce_privacy` set to `true`!*
+This protection exists to help packages have control over who their clients are. When turning on this protection, only clients who are listed in your `visible_to` metadata will be allowed to consume your package. Here is an example in `packs/apples/package.yml`:
+```yml
+enforce_privacy: true
+enforce_dependencies: true
+metadata:
+  protections:
+    prevent_other_packages_from_using_this_package_without_explicit_visibility: fail_on_new
+    # ... other protections are the same
+  visible_to:
+    - packs/other_pack
+    - packs/another_pack
+```
+In this package, only `packs/other_pack` and `packs/another_pack` can use `packs/apples`. With both the `fail_on_new` and `fail_on_any` setting, only those packs can state a dependency on `packs/apples` in their `package.yml`. If any other packs state a dependency on `packs/apples`, the build will fail, even with violations. With the `fail_on_new` setting, a pack can create a dependency or privacy violation on `packs/apples` even if it's not listed. With `fail_on_any`, no violations are allowed.
+If `visible_to` is not set and the protection is turned on, then the package cannot be consumed by any package (a top-level package might be a good candidate for this).
+
+Note that this protection's default behavior is `fail_never`, so it can remain unset in the `package.yml`.
+
+## Violation Behaviors
+#### `fail_on_any`
+If this behavior is selected, the build will fail if there is *any* issue, new or old.
+#### `fail_on_new`
+#### For protections from packwerk
+If this behavior is selected, everything that is already in `deprecated_references.yml` is considered allowed. Think of it like `.rubocop_todo.yml`. If your PR introduces a new violation that is not captured in `deprecated_references.yml`, the build will rerun `bin/packwerk check` and fail if a new violation shows up. If for whatever reason you'd like to allow for the new violation, you can simply run `bin/packwerk update-deprecations` locally and commit the changes to `deprecated_references.yml` files.
+#### For protections from rubocop
+Similar to above, but instead of `deprecated_references.yml`, violations are stored in your `.rubocop_todo.yml` file. You can add to that file to bypass protections at this level.
+
+#### `fail_never`
+If this behavior is selected, the protection will not be active.
+
+## Example Usage
+This is an example package that is focused on having a typed API that respects other teams' stated boundaries.
+
+```yml
+enforce_dependencies: true
+enforce_privacy: true
+metadata:
+  protections:
+    prevent_this_package_from_violating_its_stated_dependencies: fail_never
+    prevent_other_packages_from_using_this_packages_internals: fail_never
+    prevent_this_package_from_exposing_an_untyped_api: fail_on_any
+    prevent_this_package_from_creating_other_namespaces: fail_never
+```
+
+## PackageProtections.set_defaults!
+Calling `PackageProtections.set_defaults!(...)` will make sure that all available protections are set in the protections metadata key without changing any protection behaviors that are already set.
+
+### Example Usage
+```ruby
+# get your packages
+packages = ParsePackwerk.all
+# then set defaults
+PackageProtections.set_defaults!(packages)
+# or just set defaults for one package
+PackageProtections.set_defaults!(packages.select{|p| p.package_name == 'packs/my_package'})
+```
+
+## Incorporating into your CI Pipeline
+Your CI pipeline can execute the public API ta and fail if there are any offenses.
+
+## Discussions, Issues, Questions, and More
+To keep things organized, here are some recommended homes:
+### Issues:
+https://github.com/bigrails/package_protections/issues
+
+### Questions:
+https://github.com/bigrails/package_protections/discussions/categories/q-a
+
+### General discussions:
+https://github.com/bigrails/package_protections/discussions/categories/general
+
+### Ideas, new features, requests for change:
+https://github.com/bigrails/package_protections/discussions/categories/ideas
+
+### Showcasing your work:
+https://github.com/bigrails/package_protections/discussions/categories/show-and-tell

data/config/default.yml

@@ -0,0 +1,8 @@
+# Relevant documentation:
+#  - Inheriting config from a gem:
+#    - https://docs.rubocop.org/rubocop/configuration.html#inheriting-configuration-from-a-dependency-gem
+#  - ERB in a .rubocop.yml file
+#    - https://docs.rubocop.org/rubocop/configuration.html#pre-processing
+#  - Client usage
+#    - README.md in this repo
+<%= PackageProtections.rubocop_yml %>

data/lib/package_protections/offense.rb

@@ -0,0 +1,17 @@
+# typed: strict
+
+module PackageProtections
+  class Offense < T::Struct
+    extend T::Sig
+
+    const :file, String
+    const :message, String
+    const :violation_type, Identifier
+    const :package, ParsePackwerk::Package
+
+    sig { returns(String) }
+    def package_name
+      package.name
+    end
+  end
+end

data/lib/package_protections/per_file_violation.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+# typed: strict
+module PackageProtections
+  # Perhaps this should be in ParsePackwerk. For now, this is here to help us break down violations per file.
+  # This is analogous to `Packwerk::ReferenceOffense`
+  class PerFileViolation < T::Struct
+    extend T::Sig
+
+    const :class_name, String
+    const :filepath, String
+    const :type, String
+    const :constant_source_package, String
+    const :reference_source_package, ParsePackwerk::Package
+
+    sig { params(violation: ParsePackwerk::Violation, reference_source_package: ParsePackwerk::Package).returns(T::Array[PerFileViolation]) }
+    def self.from(violation, reference_source_package)
+      violation.files.map do |file|
+        PerFileViolation.new(
+          type: violation.type,
+          class_name: violation.class_name,
+          filepath: file,
+          constant_source_package: violation.to_package_name,
+          reference_source_package: reference_source_package
+        )
+      end
+    end
+
+    sig { returns(T::Boolean) }
+    def dependency?
+      type == 'dependency'
+    end
+
+    sig { returns(T::Boolean) }
+    def privacy?
+      type == 'privacy'
+    end
+  end
+end

data/lib/package_protections/private/colorized_string.rb

@@ -0,0 +1,97 @@
+# typed: strict
+# frozen_string_literal: true
+
+module PackageProtections
+  module Private
+    class ColorizedString
+      extend T::Sig
+
+      class Color < T::Enum
+        enums do
+          Black = new
+          Red = new
+          Green = new
+          Yellow = new
+          Blue = new
+          Pink = new
+          LightBlue = new
+          White = new
+        end
+      end
+
+      sig { params(original_string: String, color: Color).void }
+      def initialize(original_string, color = Color::White)
+        @original_string = original_string
+        @color = color
+      end
+
+      sig { returns(String) }
+      def colorized_to_s
+        "\e[#{color_code}m#{@original_string}\e[0m"
+      end
+
+      sig { returns(String) }
+      def to_s
+        @original_string
+      end
+
+      sig { returns(ColorizedString) }
+      def red
+        colorize(Color::Red)
+      end
+
+      sig { returns(ColorizedString) }
+      def green
+        colorize(Color::Green)
+      end
+
+      sig { returns(ColorizedString) }
+      def yellow
+        colorize(Color::Yellow)
+      end
+
+      sig { returns(ColorizedString) }
+      def blue
+        colorize(Color::Blue)
+      end
+
+      sig { returns(ColorizedString) }
+      def pink
+        colorize(Color::Pink)
+      end
+
+      sig { returns(ColorizedString) }
+      def light_blue
+        colorize(Color::LightBlue)
+      end
+
+      sig { returns(ColorizedString) }
+      def white
+        colorize(Color::White)
+      end
+
+      private
+
+      sig { params(color: Color).returns(ColorizedString) }
+      def colorize(color)
+        self.class.new(@original_string, color)
+      end
+
+      sig { returns(Integer) }
+      def color_code
+        case @color
+        when Color::Black then 30
+        when Color::Red then 31
+        when Color::Green then 32
+        when Color::Yellow then 33
+        when Color::Blue then 34
+        when Color::Pink then 35
+        when Color::LightBlue then 36
+        when Color::White then 37
+        else
+          T.absurd(@color)
+        end
+      end
+    end
+  end
+end

data/lib/package_protections/private/incoming_privacy_protection.rb

@@ -0,0 +1,118 @@
+# typed: strict
+# frozen_string_literal: true
+
+module PackageProtections
+  module Private
+    class IncomingPrivacyProtection
+      extend T::Sig
+
+      include ProtectionInterface
+
+      IDENTIFIER = 'prevent_other_packages_from_using_this_packages_internals'
+
+      sig { override.returns(String) }
+      def identifier
+        IDENTIFIER
+      end
+
+      sig { override.params(behavior: ViolationBehavior, package: ParsePackwerk::Package).returns(T.nilable(String)) }
+      def unmet_preconditions_for_behavior(behavior, package)
+        if behavior.enabled? && !package.enforces_privacy?
+          "Package #{package.name} must have `enforce_privacy: true` to use this protection"
+        elsif !behavior.enabled? && package.enforces_privacy?
+          "Package #{package.name} must have `enforce_privacy: false` to turn this protection off"
+        else
+          nil
+        end
+      end
+
+      sig { override.returns(String) }
+      def humanized_protection_name
+        'Privacy Violations'
+      end
+
+      sig { override.returns(String) }
+      def humanized_protection_description
+        <<~MESSAGE
+          To resolve these violations, check the `public/` folder in each pack for public constants and APIs.
+          If you need help or can't find what you need to meet your use case, reach out to the owning team.
+          See https://go/packwerk_cheatsheet_privacy for more info.
+        MESSAGE
+      end
+
+      sig do
+        override.params(
+          new_violations: T::Array[PerFileViolation]
+        ).returns(T::Array[Offense])
+      end
+      def get_offenses_for_new_violations(new_violations)
+        new_violations.select(&:privacy?).flat_map do |per_file_violation|
+          protected_package = Private.get_package_with_name(per_file_violation.constant_source_package)
+          violation_behavior = protected_package.violation_behavior_for(identifier)
+
+          case violation_behavior
+          when ViolationBehavior::FailNever
+            next []
+          when ViolationBehavior::FailOnNew
+            message = message_for_fail_on_new(per_file_violation)
+          when ViolationBehavior::FailOnAny
+            message = message_for_fail_on_any(per_file_violation)
+          else
+            T.absurd(violation_behavior)
+          end
+
+          Offense.new(
+            file: per_file_violation.filepath,
+            message: message,
+            violation_type: identifier,
+            package: protected_package.original_package
+          )
+        end
+      end
+
+      sig do
+        override.params(
+          protected_packages: T::Array[ProtectedPackage]
+        ).returns(T::Array[Offense])
+      end
+      def get_offenses_for_existing_violations(protected_packages)
+        all_listed_violations = protected_packages.flat_map do |protected_package|
+          protected_package.violations.select(&:privacy?).flat_map do |violation|
+            PerFileViolation.from(violation, protected_package.original_package)
+          end
+        end
+
+        all_listed_violations.flat_map do |per_file_violation|
+          constant_source_package = Private.get_package_with_name(per_file_violation.constant_source_package)
+          violation_behavior = constant_source_package.violation_behavior_for(identifier)
+
+          case violation_behavior
+          when ViolationBehavior::FailNever, ViolationBehavior::FailOnNew
+            []
+          when ViolationBehavior::FailOnAny
+            Offense.new(
+              file: per_file_violation.filepath,
+              message: message_for_fail_on_any(per_file_violation),
+              violation_type: identifier,
+              package: constant_source_package.original_package
+            )
+          else
+            T.absurd(violation_behavior)
+          end
+        end
+      end
+
+      private
+
+      sig { params(per_file_violation: PerFileViolation).returns(String) }
+      def message_for_fail_on_any(per_file_violation)
+        "#{message_for_fail_on_new(per_file_violation)} (`#{per_file_violation.constant_source_package}` set to `fail_on_any`)"
+      end
+
+      sig { params(per_file_violation: PerFileViolation).returns(String) }
+      def message_for_fail_on_new(per_file_violation)
+        "`#{per_file_violation.filepath}` references private `#{per_file_violation.class_name}` from `#{per_file_violation.constant_source_package}`"
+      end
+    end
+  end
+end

data/lib/package_protections/private/metadata_modifiers.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# typed: strict
+module PackageProtections
+  module Private
+    class MetadataModifiers
+      extend T::Sig
+
+      sig { params(package: ParsePackwerk::Package, protection_identifier: Identifier, violation_behavior: ViolationBehavior).returns(ParsePackwerk::Package) }
+      def self.package_with_modified_protection(package, protection_identifier, violation_behavior)
+        # We dup this to prevent mutations to the original underlying hash
+        new_metadata = package.metadata.dup
+        protections = new_metadata['protections'].dup || {}
+        protections[protection_identifier] = violation_behavior.serialize
+        new_metadata['protections'] = protections
+
+        ParsePackwerk::Package.new(
+          name: package.name,
+          enforce_dependencies: package.enforce_dependencies,
+          enforce_privacy: package.enforce_privacy,
+          dependencies: package.dependencies,
+          metadata: new_metadata
+        )
+      end
+    end
+  end
+end

data/lib/package_protections/private/multiple_namespaces_protection.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+# typed: strict
+
+module PackageProtections
+  module Private
+    class MultipleNamespacesProtection
+      extend T::Sig
+
+      include ProtectionInterface
+      include RubocopProtectionInterface
+
+      IDENTIFIER = 'prevent_this_package_from_creating_other_namespaces'
+      COP_NAME = 'PackageProtections/NamespacedUnderPackageName'
+
+      sig { override.returns(String) }
+      def identifier
+        IDENTIFIER
+      end
+
+      sig { override.params(behavior: ViolationBehavior, package: ParsePackwerk::Package).returns(T.nilable(String)) }
+      def unmet_preconditions_for_behavior(behavior, package)
+        if !behavior.enabled? && !package.metadata['global_namespaces'].nil?
+          "Invalid configuration for package `#{package.name}`. `#{identifier}` must be turned on to use `global_namespaces` configuration."
+        else
+          # We don't need to validate if the behavior is currentely fail_never
+          return if behavior.fail_never?
+
+          # The reason for this is precondition is the `MultipleNamespacesProtection` assumes this to work properly.
+          # To remove this precondition, we need to modify `MultipleNamespacesProtection` to be more generalized!
+          if EXPECTED_PACK_DIRECTORIES.include?(Pathname.new(package.name).dirname.to_s) || package.name == ParsePackwerk::ROOT_PACKAGE_NAME
+            nil
+          else
+            "Package #{package.name} must be located in one of #{EXPECTED_PACK_DIRECTORIES.join(', ')} (or be the root) to use this protection"
+          end
+        end
+      end
+
+      sig do
+        override
+          .params(packages: T::Array[ProtectedPackage])
+          .returns(T::Array[CopConfig])
+      end
+      def cop_configs(packages)
+        include_paths = T.let([], T::Array[String])
+        packages.each do |p|
+          next if p.name == ParsePackwerk::ROOT_PACKAGE_NAME
+
+          if p.violation_behavior_for(identifier).enabled?
+            include_paths << p.original_package.directory.join('app', '**', '*').to_s
+            include_paths << p.original_package.directory.join('lib', '**', '*').to_s
+          end
+        end
+
+        [
+          CopConfig.new(
+            name: COP_NAME,
+            enabled: include_paths.any?,
+            include_paths: include_paths
+          )
+        ]
+      end
+
+      sig do
+        params(package: ProtectedPackage).returns(T::Hash[T.untyped, T.untyped])
+      end
+      def custom_cop_config(package)
+        {
+          'GlobalNamespaces' => package.metadata['global_namespaces']
+        }
+      end
+
+      sig do
+        override.params(
+          protected_packages: T::Array[ProtectedPackage]
+        ).returns(T::Array[Offense])
+      end
+      def get_offenses_for_existing_violations(protected_packages)
+        exclude_list = exclude_for_rule(COP_NAME)
+        offenses = []
+
+        protected_packages.each do |package|
+          violation_behavior = package.violation_behavior_for(identifier)
+
+          case violation_behavior
+          when ViolationBehavior::FailNever, ViolationBehavior::FailOnNew
+            next
+          when ViolationBehavior::FailOnAny
+            # Continue
+          else
+            T.absurd(violation_behavior)
+          end
+
+          package.original_package.directory.glob('**/**/*.*').each do |relative_path_to_file|
+            next unless exclude_list.include?(relative_path_to_file.to_s)
+
+            file = relative_path_to_file.to_s
+            offenses << Offense.new(
+              file: file,
+              message: "`#{file}` should be namespaced under the package namespace",
+              violation_type: identifier,
+              package: package.original_package
+            )
+          end
+        end
+
+        offenses
+      end
+
+      sig { override.returns(String) }
+      def humanized_protection_name
+        'Multiple Namespaces Violations'
+      end
+
+      sig { override.returns(String) }
+      def humanized_protection_description
+        <<~MESSAGE
+          These files cannot have ANY modules/classes that are not submodules of the package's allowed namespaces.
+          This is failing because these files are in `.rubocop_todo.yml` under `#{COP_NAME}`.
+          If you want to be able to ignore these files, you'll need to open the file's package's `package.yml` file and
+          change `#{IDENTIFIER}` to `#{ViolationBehavior::FailOnNew.serialize}`
+
+          See https://go/packwerk_cheatsheet_namespaces for more info.
+        MESSAGE
+      end
+    end
+  end
+end