package_protections 0.64.0

data/lib/package_protections/private/outgoing_dependency_protection.rb

@@ -0,0 +1,117 @@
+# typed: strict
+# frozen_string_literal: true
+
+module PackageProtections
+  module Private
+    class OutgoingDependencyProtection
+      extend T::Sig
+
+      include ProtectionInterface
+
+      IDENTIFIER = 'prevent_this_package_from_violating_its_stated_dependencies'
+
+      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_dependencies?
+          "Package #{package.name} must have `enforce_dependencies: true` to use this protection"
+        elsif !behavior.enabled? && package.enforces_dependencies?
+          "Package #{package.name} must have `enforce_dependencies: false` to turn this protection off"
+        else
+          nil
+        end
+      end
+
+      sig { override.returns(String) }
+      def humanized_protection_name
+        'Dependency Violations'
+      end
+
+      sig { override.returns(String) }
+      def humanized_protection_description
+        <<~MESSAGE
+          To resolve these violations, should you add a dependency in the client's `package.yml`?
+          Is the code referencing the constant, and the referenced constant, in the right packages?
+          See https://go/packwerk_cheatsheet_dependency 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(&:dependency?).flat_map do |per_file_violation|
+          reference_source_package = Private.get_package_with_name(per_file_violation.reference_source_package.name)
+          violation_behavior = reference_source_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: reference_source_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)
+        protected_packages.flat_map do |protected_package|
+          violation_behavior = protected_package.violation_behavior_for(identifier)
+
+          case violation_behavior
+          when ViolationBehavior::FailNever, ViolationBehavior::FailOnNew
+            []
+          when ViolationBehavior::FailOnAny
+            listed_violations = protected_package.violations.select(&:dependency?).flat_map do |violation|
+              PerFileViolation.from(violation, protected_package.original_package)
+            end
+
+            listed_violations.flat_map do |per_file_violation|
+              Offense.new(
+                file: per_file_violation.filepath,
+                message: message_for_fail_on_any(per_file_violation),
+                violation_type: identifier,
+                package: protected_package.original_package
+              )
+            end
+          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.reference_source_package.name}` 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}` depends on `#{per_file_violation.class_name}` from `#{per_file_violation.constant_source_package}`"
+      end
+    end
+  end
+end

data/lib/package_protections/private/output.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# typed: strict
+module PackageProtections
+  module Private
+    class Output
+      extend T::Sig
+
+      sig { params(str: String).void }
+      def self.p(str)
+        puts str
+      end
+
+      sig { params(str: ColorizedString, colorized: T::Boolean).void }
+      def self.p_colorized(str, colorized:)
+        if colorized
+          p str.colorized_to_s
+        else
+          p str.to_s
+        end
+      end
+    end
+  end
+end

data/lib/package_protections/private/typed_api_protection.rb

@@ -0,0 +1,106 @@
+# typed: strict
+# frozen_string_literal: true
+
+module PackageProtections
+  module Private
+    class TypedApiProtection
+      extend T::Sig
+
+      include ProtectionInterface
+      include RubocopProtectionInterface
+
+      IDENTIFIER = 'prevent_this_package_from_exposing_an_untyped_api'
+      COP_NAME = 'Sorbet/StrictSigil'
+
+      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)
+        # We might decide that we should check that `package.enforces_privacy?` is true here too, since that signifies the app has decided they want
+        # a public api in `app/public`. For now, we say there are no preconditions, because the user can still make `app/public` even if they are not yet
+        # ready to enforce privacy, and they might want to enforce a typed API.
+        nil
+      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|
+          if p.violation_behavior_for(identifier).enabled?
+            directory = p.original_package.directory
+            include_paths << directory.join('app', 'public', '**', '*').to_s
+          end
+        end
+
+        [
+          CopConfig.new(
+            name: COP_NAME,
+            enabled: include_paths.any?,
+            include_paths: include_paths
+          )
+        ]
+      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 = T.let([], T::Array[Offense])
+        protected_packages.flat_map do |protected_package|
+          violation_behavior = protected_package.violation_behavior_for(identifier)
+
+          case violation_behavior
+          when ViolationBehavior::FailNever, ViolationBehavior::FailOnNew
+            next
+          when ViolationBehavior::FailOnAny
+            # Continue
+          else
+            T.absurd(violation_behavior)
+          end
+
+          protected_package.original_package.directory.glob('app/public/**/**/*.*').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 `typed: strict`",
+              violation_type: identifier,
+              package: protected_package.original_package
+            )
+          end
+        end
+
+        offenses
+      end
+
+      sig { override.returns(String) }
+      def humanized_protection_name
+        'Typed API Violations'
+      end
+
+      sig { override.returns(String) }
+      def humanized_protection_description
+        <<~MESSAGE
+          These files cannot have ANY Ruby files in the public API that are not typed strict or higher.
+          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_typed_api for more info.
+        MESSAGE
+      end
+    end
+  end
+end

data/lib/package_protections/private/visibility_protection.rb

@@ -0,0 +1,186 @@
+# typed: strict
+# frozen_string_literal: true
+
+module PackageProtections
+  module Private
+    class VisibilityProtection
+      extend T::Sig
+
+      include ProtectionInterface
+
+      IDENTIFIER = 'prevent_other_packages_from_using_this_package_without_explicit_visibility'
+
+      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)
+        # This protection relies on seeing privacy violations in other packages.
+        # We also require that the other package enforces dependencies, as otherwise, if the client is using public API, it won't show up
+        # as a privacy OR dependency violation. For now, we don't have the system structure to support that requirement.
+        if behavior.enabled? && !package.enforces_privacy?
+          "Package #{package.name} must have `enforce_privacy: true` to use this protection"
+        elsif !behavior.enabled? && !package.metadata['visible_to'].nil?
+          "Invalid configuration for package `#{package.name}`. `#{identifier}` must be turned on to use `visible_to` configuration."
+        else
+          nil
+        end
+      end
+
+      #
+      # By default, this protection does not show up when creating a new package, and its default behavior is FailNever
+      # A package that uses this protection is not considered strictly better -- in general, we want to design packages that
+      # are consumable by all packages. Therefore, a package that is consumable by all packages is the happy path.
+      #
+      # If a user wants to turn on package visibility, they must do it explicitly.
+      #
+      sig { returns(ViolationBehavior) }
+      def default_behavior
+        ViolationBehavior::FailNever
+      end
+
+      sig { override.returns(String) }
+      def humanized_protection_name
+        'Visibility Violations'
+      end
+
+      sig { override.returns(String) }
+      def humanized_protection_description
+        <<~MESSAGE
+          These files are using a constant from a package that restricts its usage through the `visible_to` flag in its `package.yml`
+          To resolve these violations, work with the team who owns the package you are trying to use and to figure out the
+          preferred public API for the behavior you want.
+
+          See https://go/packwerk_cheatsheet_visibility 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.flat_map do |per_file_violation|
+          depended_on_package = Private.get_package_with_name(per_file_violation.constant_source_package)
+          violation_behavior = depended_on_package.violation_behavior_for(identifier)
+          visible_to = depended_on_package.visible_to
+          next [] if visible_to.include?(per_file_violation.reference_source_package.name)
+
+          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: depended_on_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_offenses = T.let([], T::Array[Offense])
+
+        all_listed_violations = protected_packages.flat_map do |protected_package|
+          protected_package.violations.flat_map do |violation|
+            PerFileViolation.from(violation, protected_package.original_package)
+          end
+        end
+
+        #
+        # First we get offenses related to violations between packages, looking at all dependency and privacy
+        # violations between packages.
+        #
+
+        # We only care about looking at each edge once. Since an edge can show up twice if its both a privacy and dependency violation,
+        # we only look at each combination of class from package (A) that's referenced in package (B)
+        unique_per_file_violations = all_listed_violations.uniq do |per_file_violation|
+          [per_file_violation.reference_source_package.name, per_file_violation.constant_source_package, per_file_violation.class_name]
+        end
+
+        all_offenses += unique_per_file_violations.flat_map do |per_file_violation|
+          depended_on_package = Private.get_package_with_name(per_file_violation.constant_source_package)
+          violation_behavior = depended_on_package.violation_behavior_for(identifier)
+          visible_to = depended_on_package.visible_to
+          next [] if visible_to.include?(per_file_violation.reference_source_package.name)
+
+          case violation_behavior
+          when ViolationBehavior::FailNever, ViolationBehavior::FailOnNew
+            next []
+          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: depended_on_package.original_package
+          )
+        end
+
+        #
+        # Then we get offenses from stated dependencies
+        #
+        all_offenses += protected_packages.flat_map do |protected_package|
+          protected_package.dependencies.flat_map do |package_dependency_name|
+            depended_on_package = Private.get_package_with_name(package_dependency_name)
+            visible_to = depended_on_package.visible_to
+            next [] if visible_to.include?(protected_package.name)
+
+            violation_behavior = depended_on_package.violation_behavior_for(identifier)
+
+            case violation_behavior
+            when ViolationBehavior::FailNever
+              next []
+            when ViolationBehavior::FailOnAny, ViolationBehavior::FailOnNew
+              # continue
+            else
+              T.absurd(violation_behavior)
+            end
+
+            message = "`#{protected_package.name}` cannot state a dependency on `#{depended_on_package.name}`, as it violates package visibility in `#{depended_on_package.yml}`"
+            Offense.new(
+              file: protected_package.yml.to_s,
+              message: message,
+              violation_type: identifier,
+              package: depended_on_package.original_package
+            )
+          end
+        end
+
+        all_offenses
+      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 non-visible `#{per_file_violation.class_name}` from `#{per_file_violation.constant_source_package}`"
+      end
+    end
+  end
+end

data/lib/package_protections/private.rb

@@ -0,0 +1,155 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'package_protections/private/colorized_string'
+require 'package_protections/private/output'
+require 'package_protections/private/typed_api_protection'
+require 'package_protections/private/incoming_privacy_protection'
+require 'package_protections/private/outgoing_dependency_protection'
+require 'package_protections/private/metadata_modifiers'
+require 'package_protections/private/multiple_namespaces_protection'
+require 'package_protections/private/visibility_protection'
+
+module PackageProtections
+  #
+  # This module cannot be accessed by clients of `PackageProtections` -- only within the `PackageProtections` module itself.
+  # All implementation details are in here to keep the main `PackageProtections` module easily scannable and to keep the private things private.
+  #
+  module Private
+    extend T::Sig
+
+    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:)
+      protected_packages = packages.map { |p| ProtectedPackage.from(p) }
+
+      PackageProtections.all.flat_map do |protector|
+        protector.get_offenses(protected_packages, new_violations)
+      end
+    end
+
+    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:, verbose:)
+      information = <<~INFO
+        We will attempt to set the defaults for #{packages.count} packages!
+      INFO
+      if verbose
+        Private::Output.p_colorized Private::ColorizedString.new(information).yellow, colorized: true
+      end
+
+      new_protected_packages = []
+
+      packages.each_with_index do |package, i|
+        if verbose
+          Private::Output.p_colorized Private::ColorizedString.new("[#{i + 1}/#{packages.count}] Setting defaults for #{package.name}").yellow, colorized: true
+        end
+
+        package_protections = PackageProtections.all.select { |p| protection_identifiers.include?(p.identifier) }
+        package_protections.each do |protection|
+          # We don't set defaults when the behavior is fail never because
+          next if protection.default_behavior.fail_never?
+
+          protections = package.metadata['protections'] || {}
+          current_behavior = protections[protection.identifier]
+          next if current_behavior.present?
+
+          package = Private::MetadataModifiers.package_with_modified_protection(package, protection.identifier, protection.default_behavior)
+        end
+
+        package = ParsePackwerk::Package.new(
+          name: package.name,
+          # We set these values to be true always by default
+          enforce_dependencies: true,
+          enforce_privacy: true,
+          dependencies: package.dependencies,
+          metadata: package.metadata
+        )
+
+        new_protected_packages << ProtectedPackage.from(package)
+      end
+
+      new_protected_packages.each do |package|
+        ParsePackwerk.write_package_yml!(package.original_package)
+      end
+    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)
+      all_packages_indexed_by_name = {}
+      all_packages.each { |package| all_packages_indexed_by_name[package.name] = package }
+
+      package_names.map do |package_name|
+        clean_pack_name = package_name.gsub(%r{/$}, '')
+        package = all_packages_indexed_by_name[clean_pack_name]
+        if package.nil?
+          raise "Sorry, we couldn't find a package with name #{package_name}. Here are all of the package names we know about: #{all_packages.map(&:name).sort.inspect}"
+        end
+
+        package
+      end
+    end
+
+    sig { params(root_pathname: Pathname).returns(String) }
+    def self.rubocop_yml(root_pathname:)
+      protected_packages = Dir.chdir(root_pathname) { all_protected_packages }
+      package_protection = T.cast(PackageProtections.all.select { |p| p.is_a?(RubocopProtectionInterface) }, T::Array[RubocopProtectionInterface])
+      cop_configs = package_protection.flat_map { |p| p.cop_configs(protected_packages) }
+      cop_configs.map(&:to_rubocop_yml_compatible_format).join("\n\n")
+    end
+
+    sig do
+      returns(T::Array[ProtectedPackage])
+    end
+    def self.all_protected_packages
+      # Note -- we should get rid of Package in favor of SimplePackage
+      # Benchmark ParsePackwerk.all with package vs simple package
+      # convert tools to use ParsePackwerk::DeprecatedReferences.from(packs.directory)
+      # that should make this faster and not affect rubocop as much
+      ParsePackwerk.all.map do |p|
+        ProtectedPackage.from(p)
+      end
+    end
+
+    sig { params(name: String).returns(ProtectedPackage) }
+    def self.get_package_with_name(name)
+      @protected_packages_indexed_by_name ||= T.let(@protected_packages_indexed_by_name, T.nilable(T::Hash[String, ProtectedPackage]))
+      @protected_packages_indexed_by_name ||= all_protected_packages.each_with_object({}) { |package, index|
+        index[package.name] = package
+      }
+      @protected_packages_indexed_by_name[name] || raise(StandardError, "Could not find package #{name}")
+    end
+
+    sig { void }
+    def self.bust_cache!
+      @protected_packages_indexed_by_name = nil
+      @private_cop_config = nil
+    end
+
+    sig { params(identifier: Identifier).returns(T::Hash[T.untyped, T.untyped]) }
+    def self.private_cop_config(identifier)
+      @private_cop_config ||= T.let(@private_cop_config, T.nilable(T::Hash[T.untyped, T.untyped]))
+      @private_cop_config ||= begin
+        protected_packages = all_protected_packages
+        protection = T.cast(PackageProtections.with_identifier(identifier), PackageProtections::RubocopProtectionInterface)
+        protected_packages.map { |p| [p.name, protection.custom_cop_config(p)] }.to_h
+      end
+    end
+  end
+
+  private_constant :Private
+end

data/lib/package_protections/protected_package.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+# typed: strict
+module PackageProtections
+  class ProtectedPackage < T::Struct
+    extend T::Sig
+
+    const :original_package, ParsePackwerk::Package
+    const :protections, T::Hash[Identifier, ViolationBehavior]
+    const :deprecated_references, ParsePackwerk::DeprecatedReferences
+
+    sig { params(original_package: ParsePackwerk::Package).returns(ProtectedPackage) }
+    def self.from(original_package)
+      metadata = original_package.metadata['protections'] || {}
+
+      valid_identifiers = PackageProtections.all.map(&:identifier)
+      invalid_identifiers = metadata.keys - valid_identifiers
+
+      if invalid_identifiers.any?
+        raise IncorrectPublicApiUsageError.new("Invalid configuration for package `#{original_package.name}`. The metadata keys #{invalid_identifiers.inspect} are not valid behaviors under the `protection` metadata namespace. Valid keys are #{valid_identifiers.inspect}. See https://github.com/bigrails/package_protections#readme for more info") # rubocop:disable Style/RaiseArgs
+      end
+
+      protections = {}
+      metadata.each_key do |protection_key|
+        protection = PackageProtections.with_identifier(protection_key)
+        if !protection
+          raise IncorrectPublicApiUsageError.new("Invalid configuration for package `#{original_package.name}`. The metadata key #{protection_key} is not a valid behaviors under the `protection` metadata namespace. Valid keys are #{valid_identifiers.inspect}. See https://github.com/bigrails/package_protections#readme for more info") # rubocop:disable Style/RaiseArgs
+        end
+
+        protections[protection.identifier] = get_violation_behavior(protection, metadata, original_package)
+      end
+
+      unspecified_protections = valid_identifiers - protections.keys
+      protections_requiring_explicit_configuration = T.let([], T::Array[Identifier])
+      unspecified_protections.each do |protection_key|
+        protection = PackageProtections.with_identifier(protection_key)
+        if !protection.default_behavior.fail_never?
+          protections_requiring_explicit_configuration << protection.identifier
+        end
+        protections[protection_key] = protection.default_behavior
+      end
+
+      if protections_requiring_explicit_configuration.any?
+        error = "All protections must explicitly set unless their default behavior is `fail_never`. Missing protections: #{protections_requiring_explicit_configuration.join(', ')}"
+        raise IncorrectPublicApiUsageError, error
+      end
+
+      new(
+        original_package: original_package,
+        protections: protections,
+        deprecated_references: ParsePackwerk::DeprecatedReferences.for(original_package)
+      )
+    end
+
+    sig { params(protection: ProtectionInterface, metadata: T::Hash[T.untyped, T.untyped], package: ParsePackwerk::Package).returns(ViolationBehavior) }
+    def self.get_violation_behavior(protection, metadata, package)
+      behavior = ViolationBehavior.from_raw_value(metadata[protection.identifier])
+      unmet_preconditions = protection.unmet_preconditions_for_behavior(behavior, package)
+      if !unmet_preconditions.nil?
+        raise IncorrectPublicApiUsageError.new("#{protection.identifier} protection does not have the valid preconditions. #{unmet_preconditions}. See https://github.com/bigrails/package_protections#readme for more info") # rubocop:disable Style/RaiseArgs
+      end
+
+      behavior
+    end
+
+    sig { params(key: Identifier).returns(ViolationBehavior) }
+    def violation_behavior_for(key)
+      protections.fetch(key)
+    end
+
+    sig { returns(String) }
+    def name
+      original_package.name
+    end
+
+    sig { returns(ParsePackwerk::MetadataYmlType) }
+    def metadata
+      original_package.metadata
+    end
+
+    sig { returns(Pathname) }
+    def yml
+      original_package.yml
+    end
+
+    sig { returns(T::Array[String]) }
+    def dependencies
+      original_package.dependencies
+    end
+
+    sig { returns(T::Set[String]) }
+    def visible_to
+      Set.new(metadata['visible_to'] || [])
+    end
+
+    sig { returns(T::Array[ParsePackwerk::Violation]) }
+    def violations
+      deprecated_references.violations
+    end
+  end
+end