danger-packwerk 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cf899d973a7ead8ff19dc6f73f30f63c23bdc7fffc3f043766d8819ffbc088aa
+  data.tar.gz: 318d88c5243e9e510abef74590fb907ba97dd10afd563cd9fcebb1eea9161f40
+SHA512:
+  metadata.gz: 33fb31226007f52ddf1248e0d764816014f2371a5e48e1ba981ce6947c6f64eb6b3368e2ac628ea5912c5ec565481f3887e5fd53618ac5227816d27009034769
+  data.tar.gz: 8d391aea94c4045f26eb5232a177a35ebe597bf62239ab8e1050458b8db89739c2538a7f68cc5791d2b956f01986a1fb9ea23d4e5c72a53dc25e4aa965bbe013

data/README.md

@@ -0,0 +1,121 @@
+# danger-packwerk
+
+`danger-packwerk` integrates [`packwerk`](https://github.com/Shopify/packwerk) with [`danger`](https://github.com/danger/danger) to provide inline comments in PRs related to boundaries in a Rails application.
+
+## Installation
+Step 1: Add this line to your `Gemfile` (to whatever group your CI uses, as it is not needed in production) and `bundle install`:
+
+```ruby
+gem 'danger-packwerk', group: :test
+```
+
+Step 2: Add these to your `Dangerfile`:
+
+```ruby
+packwerk.check
+deprecated_references_yml_changes.check
+```
+
+That's it for basic usage!
+
+## Usage
+
+There are currently two danger checks that ship with `danger-packwerk`:
+1) One that runs `bin/packwerk check` and leaves inline comments in source code on new violations
+2) One that looks at changes to `deprecated_references.yml` files and leaves inline comments on added violations.
+
+In upcoming iterations, we will include other danger checks, including:
+1) A danger check that detects changes to `package.yml` files and posts user-configurable messages on the `package.yml` files that are modified.
+2) A danger check that detects changes to `packwerk.yml` files and allows you to specify the action taken when that happens.
+
+## packwerk.check
+![This is an image displaying a comment from the Danger github bot. The comment is inline with the PR in Github and displays the following text. Dependency violation: ::FeatureFlag belongs to 'packs/feature_flags', but 'packs/gusto_slack' does not specify a dependency on 'packs/feature_flags'. Are we missing an abstraction? Is the code making the reference, and the referenced constant, in the right packages? Inference details: this is a reference to ::FeatureFlag which seems to be defined in packs/feature_flags/app/models/feature_flag.rb. To receive help interpreting or resolving this error message, see: https://github.com/Shopify/packwerk/blob/main/TROUBLESHOOT.md#Troubleshooting-violations Privacy violation: '::FeatureFlag' is private to 'packs/feature_flags' but referenced from 'packs/gusto_slack'. Is there a public entrypoint in 'packs/feature_flags/app/public/' that you can use instead? Inference details: this is a reference to ::FeatureFlag which seems to be defined in packs/feature_flags/app/models/feature_flag.rb. To receive help interpreting or resolving this error message, see: https://github.com/Shopify/packwerk/blob/main/TROUBLESHOOT.md#Troubleshooting-violations](docs/basic_usage.png)
+
+Without any configuration, `packwerk.check` should just work. By default, it will post a maximum of 15 messages in a PR, using the default messaging from packwerk, and it will not fail the build.
+
+`packwerk.check` can be configured to in the following ways:
+
+### Change the message that displays in the markdown
+The default message displayed is from `bin/packwerk check`. To customize this this, pass in `offenses_formatter` to `packwerk.check` in your `Dangerfile`. Here's a simple example:
+```ruby
+packwerk.check(
+  # Offenses are a T::Array[Packwerk::ReferenceOffense] => https://github.com/Shopify/packwerk/blob/main/lib/packwerk/reference_offense.rb
+  offenses_formatter: -> (offenses) do
+    "There are #{offenses.count} packwerk offenses on this line!"
+  end
+)
+```
+
+A more advanced example could give more specific information about the violation and information specific to your organization or project about how to resolve. Here is a screenshot of what our message looks like at Gusto:
+![This is an image displaying a comment from the Danger github bot. The comment is inline with the PR in Github and displays the following text: Hi there! It looks like FeatureFlag is private API of packs/feature_flags, which is also not in packs/gusto_slack's list of dependencies. Before you run bin/packwerk update-deprecations, read through How to Handle Dependency and Privacy Violations (with Flow Chart!). Here are some quick suggestions to resolve: Does the code you are writing live in the right pack? If not, try bin/move_to_pack -n packs/destination_pack -f packs/gusto_slack/app/services/slack/client.rb. Does FeatureFlag live in the right pack? If not, try bin/move_to_pack -n packs/destination_pack -f packs/feature_flags/app/models/feature_flag.rb. Do we actually want to depend on packs/feature_flags. If so, try adding packs/feature_flags to packs/gusto_slack/package.yml dependencies. If not, what can we change about the design so we do not have to depend on packs/feature_flags? Does API in packs/feature_flags/public support this use case? If not, can we work with @Gusto/product-infrastructure to create and use a public API? If FeatureFlag should already be public, try bin/make_public -f packs/feature_flags/app/models/feature_flag.rb. Need help? Join us in #ruby-modularity or provide feedback.](docs/advanced_usage.png)
+
+### Fail the build on new violations
+Simply pass in `fail_build: true` into `check`, as such:
+```ruby
+packwerk.check(fail_build: true)
+```
+
+If you want to change the default error message, which is `Packwerk violations were detected! Please resolve them to unblock the build.`, then you can also pass in `failure_message`.
+
+### Change the max number of comments that will display
+If you do not change this, the default max is 15. More information about why we chose this number in the source code.
+```ruby
+packwerk.check(max_comments: 3)
+```
+
+### Do something extra when there are packwerk failures
+Maybe you want to notify slack or do something else when there are packwerk failures.
+
+```ruby
+packwerk.check(
+  # Offenses are a T::Array[Packwerk::ReferenceOffense] => https://github.com/Shopify/packwerk/blob/main/lib/packwerk/reference_offense.rb
+  on_failure: -> (offenses) do
+    # Notify slack or otherwise do something extra!
+  end
+)
+```
+
+## deprecated_references_yml_changes.check
+![This is an image displaying a comment from the Danger github bot. The comment is inline with the PR in Github and displays the following text. We noticed you ran `bin/packwerk update-deprecations`. Make sure to read through the docs for other ways to resolve.](docs/basic_usage_2.png)
+
+Without any configuration, `deprecated_references_yml_changes.check` should just work. By default, it will post a maximum of 15 messages in a PR, using default messaging defined within this gem.
+
+`deprecated_references_yml_changes.check` can be configured to in the following ways:
+
+### Change the message that displays in the markdown
+The default message displayed is from `lib/danger-packwerk/private/default_offenses_formatter.rb`. To customize this this, pass in `added_offenses_formatter` to `deprecated_references_yml_changes.check` in your `Dangerfile`. Here's a simple example:
+```ruby
+deprecated_references_yml_changes.check(
+  # Offenses are a T::Array[DangerPackwerk::BasicReferenceOffense]
+  added_offenses_formatter: -> (added_offenses) do
+    "There are #{added_offenses.count} new violations this line!"
+  end
+)
+```
+
+A more advanced example could give more specific information about the violation and information specific to your organization or project about how to resolve. Here is a screenshot of what our message looks like at Gusto:
+![This is an image displaying a comment from the Danger github bot. The comment is inline with the PR in Github and displays the following text. Hi again! It looks like FeatureFlag is private API of packs/feature_flags, which is also not in packs/gusto_slack's list of dependencies.. We noticed you ran bin/packwerk update-deprecations. Make sure to read through How to Handle Dependency and Privacy Violations (with Flow Chart!). Could you add some context as a reply here about why we needed to add these violations packs/gusto_slack/package.yml is configured with notify_on_new_violations to notify @Gusto/product-infrastructure (#product-infrastructure) on new dependency violations. packs/feature_flags/package.yml is configured with notify_on_new_violations to notify @Gusto/product-infrastructure (#product-infrastructure) on new privacy violations
+Need help? Join us in #ruby-modularity or provide feedback.
+](docs/advanced_usage_2.png)
+
+### Change the max number of comments that will display
+If you do not change this, the default max is 15. More information about why we chose this number in the source code.
+```ruby
+deprecated_references_yml_changes.check(max_comments: 3)
+```
+
+### Do something extra before we leave comments
+Maybe you want to notify slack or do something else before we leave comments.
+
+```ruby
+deprecated_references_yml_changes.check(
+  # violation_diff is a DangerPackwerk::ViolationDiff and changed_deprecated_references_ymls is a T::Array[String]
+  before_comment: -> (violation_diff, changed_deprecated_references_ymls) do
+    # Notify slack or otherwise do something extra!
+  end
+)
+```
+
+## Development
+
+We welcome your contributions! Please create an issue or pull request and we'd be happy to take a look.

data/lib/danger-packwerk/basic_reference_offense.rb

@@ -0,0 +1,106 @@
+# typed: strict
+
+module DangerPackwerk
+  #
+  # We call this BasicReferenceOffense as it is intended to have a subset of the interface of Packwerk::ReferenceOffense, located here:
+  # https://github.com/Shopify/packwerk/blob/a22862b59f7760abf22bda6804d41a52d05301d8/lib/packwerk/reference_offense.rb#L1
+  # However, we cannot actually construct a Packwerk::ReferenceOffense from `deprecated_referencs.yml` alone, since they are normally
+  # constructed in packwerk when packwerk parses the AST and actually outputs `deprecated_references.yml`, a process in which some information,
+  # such as the location where the constant is defined, is lost.
+  #
+  class BasicReferenceOffense < T::Struct
+    class Location < T::Struct
+      extend T::Sig
+
+      const :file, String
+      const :line_number, Integer
+
+      #
+      # These two methods exist so we can use `group_by` to group a `T::Array[BasicReferenceOffense]` by location.
+      #
+      sig { params(other: Location).returns(T::Boolean) }
+      def eql?(other)
+        file == other.file && line_number == other.line_number
+      end
+
+      sig { returns(Integer) }
+      def hash
+        [file, line_number].hash
+      end
+      #
+      # End method group
+      #
+    end
+
+    extend T::Sig
+
+    const :class_name, String
+    const :file, String
+    const :to_package_name, String
+    const :type, String
+    const :location, Location
+
+    sig { params(deprecated_references_yml: String).returns(T::Array[BasicReferenceOffense]) }
+    def self.from(deprecated_references_yml)
+      deprecated_references_yml_pathname = Pathname.new(deprecated_references_yml)
+      violations = Private::DeprecatedReferences.from(deprecated_references_yml_pathname).violations
+
+      violations.flat_map do |violation|
+        # We choose the location of the violation as the reference to the constant within the `deprecated_references.yml` file.
+        # We simply find the reference to that constant, because we know that each constant reference can occur only once per `deprecated_references.yml` file
+        # The reason for this is that we know that only one file in the codebase can define a constant, and packwerk's constant_resolver will actually
+        # raise if this assumption is not true: https://github.com/Shopify/constant_resolver/blob/e78af0c8d5782b06292c068cfe4176e016c51b34/lib/constant_resolver.rb#L74
+        #
+        # Note though that since one constant reference in a `deprecated_referencs.yml` can be both a privacy and a dependency violation AND it can occur in many files,
+        # we need to group them. That is -- if `MyPrivateConstant` is both a dependency and a privacy violation AND it occurs in 10 files, that would represent 20 violations.
+        # Therefore we will group all of those 20 into one message to the user rather than providing 20 messages.
+        _line, line_number = deprecated_references_yml_pathname.readlines.each_with_index.find { |line, _index| line.include?(violation.class_name) }
+        if line_number.nil?
+          debug_info = { class_name: violation.class_name, to_package_name: violation.to_package_name, type: violation.type }
+          raise "Unable to find reference to violation #{debug_info} in #{deprecated_references_yml}"
+        end
+
+        # We add one to the line number since `each_with_index` is zero-based indexed but Github line numbers are one-based indexed
+        location = Location.new(file: deprecated_references_yml, line_number: line_number + 1)
+
+        violation.files.map do |file|
+          BasicReferenceOffense.new(
+            class_name: violation.class_name,
+            file: file,
+            to_package_name: violation.to_package_name,
+            type: violation.type,
+            location: location
+          )
+        end
+      end
+    end
+
+    sig { returns(T::Boolean) }
+    def privacy?
+      type == 'privacy'
+    end
+
+    sig { returns(T::Boolean) }
+    def dependency?
+      type == 'dependency'
+    end
+
+    sig { params(other: BasicReferenceOffense).returns(T::Boolean) }
+    def ==(other)
+      other.class_name == class_name &&
+        other.file == file &&
+        other.to_package_name == to_package_name &&
+        other.type == type
+    end
+
+    sig { params(other: BasicReferenceOffense).returns(T::Boolean) }
+    def eql?(other)
+      self == other
+    end
+
+    sig { returns(Integer) }
+    def hash
+      [class_name, file, to_package_name, type].hash
+    end
+  end
+end

data/lib/danger-packwerk/danger_deprecated_references_yml_changes.rb

@@ -0,0 +1,140 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'danger'
+require 'sorbet-runtime'
+require 'danger-packwerk/private'
+require 'danger-packwerk/basic_reference_offense'
+require 'danger-packwerk/violation_diff'
+require 'open3'
+
+module DangerPackwerk
+  class DangerDeprecatedReferencesYmlChanges < Danger::Plugin
+    extend T::Sig
+
+    # We choose 5 here because violation additions tend to fall into a bimodal distribution, where most PRs only add a handful (<10) of new violations,
+    # but there are some that do a rename of an often-used variable, which can change hundreds of violations.
+    # Therefore we hope to capture the majority case of people making changes to code while not spamming PRs that do a big rename.
+    # We set a max (rather than unlimited) to avoid GitHub rate limiting and general spam if a PR does some sort of mass rename.
+    DEFAULT_MAX_COMMENTS = 5
+    AddedOffensesFormatter = T.type_alias { T.proc.params(added_violations: T::Array[BasicReferenceOffense]).returns(String) }
+    DEFAULT_ADDED_OFFENSES_FORMATTER = T.let(->(added_violations) { Private::DefaultAddedOffensesFormatter.format(added_violations) }, AddedOffensesFormatter)
+    BeforeComment = T.type_alias { T.proc.params(violation_diff: ViolationDiff, changed_deprecated_references_ymls: T::Array[String]).void }
+    DEFAULT_BEFORE_COMMENT = T.let(->(violation_diff, changed_deprecated_references_ymls) {}, BeforeComment)
+
+    sig do
+      params(
+        added_offenses_formatter: AddedOffensesFormatter,
+        before_comment: BeforeComment,
+        max_comments: Integer
+      ).void
+    end
+    def check(
+      added_offenses_formatter: DEFAULT_ADDED_OFFENSES_FORMATTER,
+      before_comment: DEFAULT_BEFORE_COMMENT,
+      max_comments: DEFAULT_MAX_COMMENTS
+    )
+      changed_deprecated_references_ymls = (git.modified_files + git.added_files + git.deleted_files).grep(DEPRECATED_REFERENCES_PATTERN)
+
+      violation_diff = get_violation_diff
+
+      before_comment.call(
+        violation_diff,
+        changed_deprecated_references_ymls.to_a
+      )
+
+      current_comment_count = 0
+      violation_diff.added_violations.group_by(&:location).each do |location, violations|
+        break if current_comment_count >= max_comments
+
+        markdown(
+          added_offenses_formatter.call(violations),
+          line: location.line_number,
+          file: location.file
+        )
+
+        current_comment_count += 1
+      end
+    end
+
+    sig { returns(ViolationDiff) }
+    def get_violation_diff # rubocop:disable Naming/AccessorMethodName
+      added_violations = T.let([], T::Array[BasicReferenceOffense])
+      removed_violations = T.let([], T::Array[BasicReferenceOffense])
+
+      git.added_files.grep(DEPRECATED_REFERENCES_PATTERN).each do |added_deprecated_references_yml_file|
+        # Since the file is added, we know on the base commit there are no violations related to this pack,
+        # and that all violations from this file are new
+        added_violations += BasicReferenceOffense.from(added_deprecated_references_yml_file)
+      end
+
+      git.deleted_files.grep(DEPRECATED_REFERENCES_PATTERN).each do |deleted_deprecated_references_yml_file|
+        # Since the file is deleted, we know on the HEAD commit there are no violations related to this pack,
+        # and that all violations from this file are deleted
+        removed_violations += get_violations_before_patch_for(deleted_deprecated_references_yml_file)
+      end
+
+      git.modified_files.grep(DEPRECATED_REFERENCES_PATTERN).each do |modified_deprecated_references_yml_file|
+        head_commit_violations = BasicReferenceOffense.from(modified_deprecated_references_yml_file)
+        base_commit_violations = get_violations_before_patch_for(modified_deprecated_references_yml_file)
+
+        added_violations += head_commit_violations - base_commit_violations
+        removed_violations += base_commit_violations - head_commit_violations
+      end
+
+      ViolationDiff.new(
+        added_violations: added_violations,
+        removed_violations: removed_violations
+      )
+    end
+
+    private
+
+    sig { params(deprecated_references_yml_file: String).returns(T::Array[BasicReferenceOffense]) }
+    def get_violations_before_patch_for(deprecated_references_yml_file)
+      # The strategy to get the violations before this PR is to reverse the patch on each `deprecated_references.yml`.
+      # A previous strategy attempted to use `git merge-base --fork-point`, but there are many situations where it returns
+      # empty values. That strategy is fickle because it depends on the state of the `reflog` within the CI suite, which appears
+      # to not be reliable to depend on.
+      #
+      # Instead, just inverting the patch should hopefully provide a more reliable way to figure out what was the state of the file before
+      # the PR without needing to use git commands that interpret the branch history based on local git history.
+      #
+      # We apply the patch to the original file so that we can seamlessly reverse the patch applied to that file (since patches are coupled to
+      # the files they modify). After parsing the violations from that `deprecated_references.yml` file with the patch reversed,
+      # we use a temporary copy of the original file to rewrite to it with the original contents.
+      # Note that practically speaking, we don't need to rewrite the original contents (since we already fetched the
+      # original contents above and the CI file system should be ephemeral). However, we do this anyways in case we later change these
+      # assumptions, or another client's environment is different and expects these files not to be mutated.
+
+      # Keep track of the original file contents. If the original file has been deleted, then we delete the file after inverting the patch at the end, rather than rewriting it.
+      deprecated_references_yml_file_copy = (File.read(deprecated_references_yml_file) if File.exist?(deprecated_references_yml_file))
+
+      Tempfile.create do |patch_file|
+        # Normally we'd use `git.diff_for_file(deprecated_references_yml_file).patch` here, but there is a bug where it does not work for deleted files yet.
+        # I have a fix for that here: https://github.com/danger/danger/pull/1357
+        # Until that lands, I'm just using the underlying implementation of that method to get the diff for a file.
+        # Note that I might want to use a safe escape operator, `&.patch` and return gracefully if the patch cannot be found.
+        # However I'd be interested in why that ever happens, so for now going to proceed as is.
+        # (Note that better yet we'd have observability into these so I can just log under those circumstances rather than surfacing an error to the user,
+        # but we don't have that quite yet.)
+        patch_for_file = git.diff[deprecated_references_yml_file].patch
+        # This appears to be a known issue that patches require new lines at the end. It seems like this is an issue with Danger that
+        # it gives us a patch without a newline.
+        # https://stackoverflow.com/questions/18142870/git-error-fatal-corrupt-patch-at-line-36
+        patch_file << "#{patch_for_file}\n"
+        patch_file.rewind
+        # https://git-scm.com/docs/git-apply
+        _stdout, _stderr, _status = Open3.capture3("git apply --reverse #{patch_file.path}")
+        # https://www.rubyguides.com/2019/05/ruby-tempfile/
+        BasicReferenceOffense.from(deprecated_references_yml_file)
+      end
+    ensure
+      if deprecated_references_yml_file_copy
+        File.write(deprecated_references_yml_file, deprecated_references_yml_file_copy)
+      else
+        File.delete(deprecated_references_yml_file)
+      end
+    end
+  end
+end

data/lib/danger-packwerk/danger_packwerk.rb

@@ -0,0 +1,104 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'danger'
+require 'packwerk'
+require 'sorbet-runtime'
+require 'danger-packwerk/packwerk_wrapper'
+
+module DangerPackwerk
+  # Note that Danger names the plugin (i.e. anything that inherits from `Danger::Plugin`) by taking the name of the class and gsubbing out "Danger"
+  # Therefore this plugin is simply called "packwerk"
+  class DangerPackwerk < Danger::Plugin
+    extend T::Sig
+
+    # We choose 15 because we want to err on the side of completeness and give users all of the information they need to help make their build pass,
+    # especially given all violations should fail the build anyways.
+    # We set a max (rather than unlimited) to avoid GitHub rate limiting and general spam if a PR does some sort of mass rename.
+    DEFAULT_MAX_COMMENTS = 15
+    OnFailure = T.type_alias { T.proc.params(offenses: T::Array[Packwerk::ReferenceOffense]).void }
+    DEFAULT_ON_FAILURE = T.let(->(offenses) {}, OnFailure)
+    OffensesFormatter = T.type_alias { T.proc.params(offenses: T::Array[Packwerk::ReferenceOffense]).returns(String) }
+    DEFAULT_OFFENSES_FORMATTER = T.let(->(offenses) { offenses.map(&:message).join("\n\n") }, OffensesFormatter)
+    DEFAULT_FAIL = false
+    DEFAULT_FAILURE_MESSAGE = 'Packwerk violations were detected! Please resolve them to unblock the build.'
+
+    sig do
+      params(
+        max_comments: Integer,
+        offenses_formatter: OffensesFormatter,
+        fail_build: T::Boolean,
+        failure_message: String,
+        on_failure: OnFailure
+      ).void
+    end
+    def check(
+      max_comments: DEFAULT_MAX_COMMENTS,
+      offenses_formatter: DEFAULT_OFFENSES_FORMATTER,
+      fail_build: DEFAULT_FAIL,
+      failure_message: DEFAULT_FAILURE_MESSAGE,
+      on_failure: DEFAULT_ON_FAILURE
+    )
+      # This is important because by default, Danger will leave a concantenated list of all its messages if it can't find a commentable place in the
+      # diff to leave its message. This is an especially bad UX because it will be a huge wall of text not connected to the source of the issue.
+      # Furthermore, dismissing these ensures that something like moving a file from pack to pack does not trigger the danger message. That is,
+      # the danger message will only be triggered by actual code that someone has actually written in their PR.
+      # Another example would be if someone changes the list of dependencies of a package (e.g. to resolve a cyclic dependency). This would not
+      # trigger the warning message, which is good, since we only want to trigger on new code.
+      github.dismiss_out_of_range_messages
+
+      # https://github.com/danger/danger/blob/eca19719d3e585fe1cc46bc5377f9aa955ebf609/lib/danger/danger_core/plugins/dangerfile_git_plugin.rb#L80
+      renamed_files_after = git.renamed_files.map { |f| f[:after] }
+      targeted_files = (git.modified_files + git.added_files + renamed_files_after).select do |f|
+        path = Pathname.new(f)
+
+        # We probably want to check the `include` key of `packwerk.yml`. By default, this value is "**/*.{rb,rake,erb}",
+        # so we hardcode this in for now. If this blocks a user, we can take that opportunity to read from `packwerk.yml`.
+        extension_is_targeted = ['.erb', '.rake', '.rb'].include?(path.extname)
+
+        # If a file has been modified via a rename, then `git.modified_files` will return an array that includes that file's *original* name.
+        # Packwerk will ignore input files that do not exist, and when the PR only contains renamed Ruby files, that means packwerk check works
+        # off of an empty list. It's default behavior in that case is to scan *all* files, which can lead to abnormally long run times.
+        # To avoid this, we gracefully return if there are no targeted files.
+        # To avoid false negatives, we also look at renamed files after (above)
+        file_exists = path.exist?
+
+        extension_is_targeted && file_exists
+      end
+
+      return if targeted_files.empty?
+
+      current_comment_count = 0
+
+      packwerk_reference_offenses = PackwerkWrapper.get_offenses_for_files(targeted_files.to_a).compact
+
+      # We group by the constant name, line number, and reference path. Any offenses with these same values should only differ on what type of violation
+      # they are (privacy or dependency). We put privacy and dependency violation messages in the same comment since they would occur on the same line.
+      packwerk_reference_offenses.group_by do |packwerk_reference_offense|
+        [
+          packwerk_reference_offense.reference.constant.name,
+          packwerk_reference_offense.location.line,
+          packwerk_reference_offense.reference.relative_path
+        ]
+      end.each do |_group, unique_packwerk_reference_offenses|
+        break if current_comment_count >= max_comments
+
+        current_comment_count += 1
+
+        reference_offense = T.must(unique_packwerk_reference_offenses.first)
+        line_number = reference_offense.location.line
+        referencing_file = reference_offense.reference.relative_path
+
+        message = offenses_formatter.call(unique_packwerk_reference_offenses)
+
+        markdown(message, file: referencing_file, line: line_number)
+      end
+
+      if current_comment_count > 0
+        fail(failure_message) if fail_build
+
+        on_failure.call(packwerk_reference_offenses)
+      end
+    end
+  end
+end

data/lib/danger-packwerk/packwerk_wrapper.rb

@@ -0,0 +1,65 @@
+# typed: strict
+
+module DangerPackwerk
+  # This class wraps packwerk to give us precisely what we want, which is the `Packwerk::ReferenceOffense` from a set of files.
+  # Note that statically packwerk returns `Packwerk::Offense` from running `bin/packwerk check`. The two types of `Packwerk::Offense` are
+  # `Packwerk::ReferenceOffense` and `Packwerk::Parsers::ParseResult`.`Packwerk::ReferenceOffense` inherits from `Packwerk::Offense`, and has more info than `Packwerk::Offense`.
+  # `Packwerk::Parsers::ParseResult` is returned when there is a file parsing issue. We ignore ParseResult types as it's likely that other tests would break along with this Danger check.
+  # and it is not the intent of this check to look for syntax errors in code.
+  #
+  # Also note that we would not need most of this class if there were two changes made to Packwerk:
+  # 1) It did not raise if no checkable files were found (I think it might make more sense to just return successfully rather than raise). This occurs if the
+  # input file list is excluded from the user's `exclude` list. In this case, check should return that no errors were found, since those files were not analyzed.
+  # 2) If the CLI gave a way to get offenses from files without this somewhat hacky way of passing in a formatter that stores the offenses.
+  class PackwerkWrapper
+    extend T::Sig
+
+    sig { params(files: T::Array[String]).returns(T::Array[Packwerk::ReferenceOffense]) }
+    def self.get_offenses_for_files(files)
+      formatter = OffensesAggregatorFormatter.new
+      # This is mostly copied from exe/packwerk within the packwerk gem, but we use our own formatters
+      ENV['RAILS_ENV'] = 'test'
+      style = Packwerk::OutputStyles::Coloured.new
+      cli = Packwerk::Cli.new(style: style, offenses_formatter: formatter)
+      cli.execute_command(['check', *files])
+      reference_offenses = formatter.aggregated_offenses.compact.select { |offense| offense.is_a?(Packwerk::ReferenceOffense) }
+      T.cast(reference_offenses, T::Array[Packwerk::ReferenceOffense])
+    rescue SystemExit => e
+      # Packwerk should probably exit positively here rather than raising an error -- there should be no
+      # errors if the user has excluded all files being checked.
+      if e.message == 'No files found or given. Specify files or check the include and exclude glob in the config file.'
+        []
+      else
+        raise
+      end
+    end
+
+    #
+    # This Packwerk formatter simply collects offenses. Ideally we could accomplish this by calling into public API of the CLI,
+    # but right now this is the only way to get the raw offenses out of packwerk.
+    #
+    class OffensesAggregatorFormatter
+      extend T::Sig
+      include Packwerk::OffensesFormatter
+
+      sig { returns(T::Array[Packwerk::Offense]) }
+      attr_reader :aggregated_offenses
+
+      sig { void }
+      def initialize
+        @aggregated_offenses = T.let([], T::Array[Packwerk::ReferenceOffense])
+      end
+
+      sig { override.params(offenses: T::Array[T.nilable(Packwerk::Offense)]).returns(String) }
+      def show_offenses(offenses)
+        @aggregated_offenses = T.unsafe(offenses)
+        ''
+      end
+
+      sig { override.params(offense_collection: Packwerk::OffenseCollection).returns(String) }
+      def show_stale_violations(offense_collection)
+        ''
+      end
+    end
+  end
+end

data/lib/danger-packwerk/private/default_offenses_formatter.rb

@@ -0,0 +1,38 @@
+# typed: strict
+
+module DangerPackwerk
+  module Private
+    class DefaultAddedOffensesFormatter
+      extend T::Sig
+
+      sig { params(violations: T::Array[BasicReferenceOffense]).returns(String) }
+      def self.format(violations)
+        violation = T.must(violations.first)
+        # We remove leading double colons as they feel like an implementation detail of packwerk.
+        constant_name = violation.class_name.gsub(/\A::/, '')
+        link_to_docs = '[the docs](https://github.com/Shopify/packwerk/blob/b647594f93c8922c038255a7aaca125d391a1fbf/docs/new_violation_flow_chart.pdf)'
+        disclaimer = "We noticed you ran `bin/packwerk update-deprecations`. Make sure to read through #{link_to_docs} for other ways to resolve. "
+        pluralized_violation = violations.count > 1 ? 'these violations' : 'this violation'
+        request_to_add_context = "Could you add some context as a reply here about why we needed to add #{pluralized_violation}?"
+
+        if violations.any?(&:dependency?) && violations.any?(&:privacy?)
+          <<~MESSAGE
+            Hi! It looks like the pack defining `#{constant_name}` considers this private API, and it's also not in the referencing pack's list of dependencies.
+            #{disclaimer}#{request_to_add_context}
+          MESSAGE
+        elsif violations.any?(&:dependency?)
+          <<~MESSAGE
+            Hi! It looks like the pack defining `#{constant_name}` is not in the referencing pack's list of dependencies.
+            #{disclaimer}#{request_to_add_context}
+          MESSAGE
+        else # violations.any?(&:privacy?)
+          <<~MESSAGE
+            Hi! It looks like the pack defining `#{constant_name}` considers this private API.
+            #{disclaimer}
+            #{request_to_add_context}
+          MESSAGE
+        end
+      end
+    end
+  end
+end

data/lib/danger-packwerk/private/deprecated_references.rb

@@ -0,0 +1,65 @@
+# typed: strict
+
+module DangerPackwerk
+  module Private
+    #
+    # The `Violation` and `DeprecatedReferences` classes come from Gusto's private `ParsePackwerk` gem.
+    # Until we decide to open source that gem, we inline these as a private implementation detail of `DangerPackwerk` for now.
+    #
+    class Violation < T::Struct
+      extend T::Sig
+
+      const :type, String
+      const :to_package_name, String
+      const :class_name, String
+      const :files, T::Array[String]
+
+      sig { returns(T::Boolean) }
+      def dependency?
+        type == 'dependency'
+      end
+
+      sig { returns(T::Boolean) }
+      def privacy?
+        type == 'privacy'
+      end
+    end
+
+    class DeprecatedReferences < T::Struct
+      extend T::Sig
+
+      const :pathname, Pathname
+      const :violations, T::Array[Violation]
+
+      sig { params(pathname: Pathname).returns(DeprecatedReferences) }
+      def self.from(pathname)
+        if pathname.exist?
+          deprecated_references_loaded_yml = YAML.load_file(pathname)
+
+          all_violations = []
+          deprecated_references_loaded_yml&.each_key do |to_package_name|
+            deprecated_references_per_package = deprecated_references_loaded_yml[to_package_name]
+            deprecated_references_per_package.each_key do |class_name|
+              symbol_usage = deprecated_references_per_package[class_name]
+              files = symbol_usage['files']
+              violations = symbol_usage['violations']
+              all_violations << Violation.new(type: 'dependency', to_package_name: to_package_name, class_name: class_name, files: files) if violations.include? 'dependency'
+
+              all_violations << Violation.new(type: 'privacy', to_package_name: to_package_name, class_name: class_name, files: files) if violations.include? 'privacy'
+            end
+          end
+
+          new(
+            pathname: pathname.cleanpath,
+            violations: all_violations
+          )
+        else
+          new(
+            pathname: pathname.cleanpath,
+            violations: []
+          )
+        end
+      end
+    end
+  end
+end