packwerk 2.2.2 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e1c2cdab1129d016428019597dc9f19dbf0836d0c545a13ce780486bf9fbba1
-  data.tar.gz: d9556ef773c776283a30f8e22308f0068e4d1a4ea918e81af44a0e126c0ca62e
+  metadata.gz: 94a6e793dd2c071a7bfb9a739fb6aaf2e07b0d2183bf743afb38da5e3847f0e2
+  data.tar.gz: dd779094dad5572746476d25d63e26f29819cf0b57519f73a4f693610cfd238e
 SHA512:
-  metadata.gz: 74cb6f2c95a7d51dc8e5199a47601b53897c29cfd6dde5d0c0ada40566d19bf0f9d0f0fcf9209dbe5b9e0ccbbcfcac9c1282fa74377af0b8e6cee63e75204948
-  data.tar.gz: d03e35ab0975d457a9202d2df2f697372f22f5a4072880dc7d308b87581ffd5a30446b8b235b221da0655cd4b31be58552b0a3f658e15a8c48d78cdee23f9794
+  metadata.gz: 9ff4d2a2aa7b6cb34e59362321ea3fb22826d10430addeef1b6143408d1a1b510ff8915105f2e74e9173334dfcfbd0a76610ea00242a2720c6feb9c75b53556f
+  data.tar.gz: 7ed4cbe3376821d54a5a58e2bc25ac3baf1f03a84928e027c0e1e1f39d52a14df4e18cc8d9ecfa50de3756507f46c0e9687d04464d3ec149037a7fdecb8eed0e

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    packwerk (2.2.2)
+    packwerk (2.3.0)
       activesupport (>= 5.2)
       ast
       better_html

data/RESOLVING_VIOLATIONS.md

@@ -3,27 +3,27 @@
 Violations can be [recorded as a deprecation](#recording-violations) or (better!) [eliminated](#eliminating-violations).
 
 ## Recording Violations
-💡 New privacy and dependency violations are never hard-blocked. There are many very valid reasons to run `bin/packwerk update-deprecations`, adding new violations to `deprecated_references.yml` files. Even if you feel your reason might not be "valid," if your judgement says adding the violation and shipping your change will produce positive impact, trust your gut.
+💡 New privacy and dependency violations are never hard-blocked. There are many very valid reasons to run `bin/packwerk update-todo`, adding new violations to `package_todo.yml` files. Even if you feel your reason might not be "valid," if your judgement says adding the violation and shipping your change will produce positive impact, trust your gut.
 
 ### Emergency Fixes
 ❔ Is it a revert or is there a lot of urgency because you are fixing a production bug impacting customers?
 
-➡️ Simply run `bin/packwerk update-deprecations`, and address the violation when the customer issue is resolved.
+➡️ Simply run `bin/packwerk update-todo`, and address the violation when the customer issue is resolved.
 
 ### Improving System Design
 ❔ Are you improving system boundaries by renaming or moving a file, class, constant,` or module?
 
-➡️ Simply run `bin/packwerk update-deprecations`. We've improved how our system is organized, so the new violations are natural.
+➡️ Simply run `bin/packwerk update-todo`. We've improved how our system is organized, so the new violations are natural.
 
 ### Making Things Explicit
 ❔ Are you making something that was implicit (hidden to Packwerk) explicit, such as adding a Sorbet signature, using a class instead of a method call, or something similar?
 
-➡️ Simply run `bin/packwerk update-deprecations`. Making something implicit explicit and capturing that as a new violation is a strict improvement.
+➡️ Simply run `bin/packwerk update-todo`. Making something implicit explicit and capturing that as a new violation is a strict improvement.
 
 ### Temporary State
 ❔ Is the violation temporary because you will soon delete the code or is it part of a refactor to improve system boundaries and reduce violations overall?
 
-➡️ Simply run `bin/packwerk update-deprecations`. Sometimes things get "worse" before they get better.
+➡️ Simply run `bin/packwerk update-todo`. Sometimes things get "worse" before they get better.
 
 ### Delivering Features
 ❔ Are you in a rush to get a feature out and product, your manager, or an internal sense of urgency has made you feel like you can't resolve system design issues?
@@ -57,7 +57,7 @@ An explicit and implementation-hiding public API is a cornerstone of well-modula
 
 ➡️  Work together on a new public API and use that instead! If the thing we're using should be public, move it to the public folder to make it public!
 
-⛈️ If working with the package's owner to improve the API is not possible, run `bin/packwerk update-deprecations`. Add some context to your PR about why it's not possible.
+⛈️ If working with the package's owner to improve the API is not possible, run `bin/packwerk update-todo`. Add some context to your PR about why it's not possible.
 
 ### Dependency Violations
 💡  Packwerk thinks something is a dependency violation if you're referencing a constant, class, module defined ANYWHERE but your package doesn't list it as an explicit dependency in its `package.yml`. We care about these because it allows us to be systematically intentional about what our code needs to run and helps us untangle and remove dependency cycles from our system.
@@ -78,4 +78,4 @@ Thoughtful dependency management is another cornerstone of well-modularized code
 
 ➡️  Work with the owners of the relevant packages, as well as your team, to think through a design that doesn't include the unwanted dependency.
 
-⛈️ If this is not possible within the scope of your changes (think hard about this one!), run `bin/packwerk update-deprecations`. Add some context to your PR about why it's not possible, and any additional context you may have, such as a possible solution.
+⛈️ If this is not possible within the scope of your changes (think hard about this one!), run `bin/packwerk update-todo`. Add some context to your PR about why it's not possible, and any additional context you may have, such as a possible solution.

data/TROUBLESHOOT.md

@@ -16,7 +16,7 @@ You can specify folders or packages in Packwerk commands for a shorter run time:
 
      bin/packwerk check components/your_package
 
-     bin/packwerk update-deprecations components/your_package
+     bin/packwerk update-todo components/your_package
 
 _Note: You cannot specify folders or packages for `bin/packwerk validate` because the command runs for the entire application._
 

data/USAGE.md

@@ -20,7 +20,7 @@
 * [Resolving new violations](#resolving-new-violations)
   * [Understanding how to respond to new violations](#understanding-how-to-respond-to-new-violations)
 * [Recording existing violations](#recording-existing-violations)
-  * [Understanding the list of deprecated references](#understanding-the-list-of-deprecated-references)
+  * [Understanding the package todo file](#understanding-the-package-todo-file)
 
 ## What problem does Packwerk solve?
 
@@ -235,28 +235,28 @@ See: [RESOLVING_VIOLATIONS.md](RESOLVING_VIOLATIONS.md)
 
 For existing codebases, packages are likely to have existing boundary violations.
 
-If so, you will want to stop the bleeding and prevent more violations from occuring. The existing violations in the codebase can be recorded in a [deprecated references list](#Understanding_the_list_of_deprecated_references) by executing:
+If so, you will want to stop the bleeding and prevent more violations from occuring. The existing violations in the codebase can be recorded in a [todo list](#understanding-the-package-todo-file) by executing:
 
-    bin/packwerk update-deprecations
+    bin/packwerk update-todo
 
-Similar to `bin/packwerk check`, you may also run `bin/packwerk update-deprecations` on folders or packages:
+Similar to `bin/packwerk check`, you may also run `bin/packwerk update-todo` on folders or packages:
 
-    bin/packwerk update-deprecations components/your_package
+    bin/packwerk update-todo components/your_package
 
 ![](static/packwerk_update.gif)
 
 _Note: Changing dependencies or enabling dependencies will not require a full update of the codebase, only the package that changed. On the other hand, changing or enabling privacy will require a full update of the codebase._
 
-`bin/packwerk update-deprecations` should only be run to record existing violations and to remove deprecated references that have been worked off. Running `bin/packwerk update-deprecations` to resolve a violation should be the very last resort.
+`bin/packwerk update-todo` should only be run to record existing violations and to remove violations that have been worked off. Running `bin/packwerk update-todo` to resolve a violation should be the very last resort.
 
 See: [TROUBLESHOOT.md - Troubleshooting violations](TROUBLESHOOT.md#Troubleshooting_violations)
 
 
-### Understanding the list of deprecated references
+### Understanding the package todo file
 
-The deprecated references list is called `deprecated_references.yml` and can be found in the package folder. The list outlines the constant violations of the package, where the violation is located, and the file defining the violation.
+The package TODO list is called `package_todo.yml` and can be found in the package folder. The list outlines the constant violations of the package, where the violation is located, and the file defining the violation.
 
-The deprecated references list should not be added to, but worked off over time.
+The package TODO list should not be added to, but worked off over time.
 
 ```yaml
 components/merchant:
@@ -267,11 +267,11 @@ components/merchant:
     - components/merchant/app/public/merchant/generate_order.rb
 ```
 
-Above is an example of a constant violation entry in `deprecated_references.yml`.
+Above is an example of a constant violation entry in `package_todo.yml`.
 
 * `components/merchant` - package where the constant violation is found
 * `::Checkouts::Core::CheckoutId` - violated constant in question
 * `dependency` - type of violation, either dependency or privacy
 * `components/merchant/app/public/merchant/generate_order.rb` - path to the file containing the violated constant
 
-Violations exist within the package that makes a violating reference. This means privacy violations of your package can be found listed in `deprecated_references.yml` files in the packages with the reference to a private constant.
+Violations exist within the package that makes a violating reference. This means privacy violations of your package can be found listed in `package_todo.yml` files in the packages with the reference to a private constant.

data/lib/packwerk/cli.rb

@@ -55,7 +55,17 @@ module Packwerk
       when "detect-stale-violations"
         output_result(parse_run(args).detect_stale_violations)
       when "update-deprecations"
-        output_result(parse_run(args).update_deprecations)
+        warning = <<~WARNING.squish
+          DEPRECATION WARNING: `update-deprecations` is deprecated in favor of
+          `update-todo`.
+        WARNING
+
+        warn(warning)
+        output_result(parse_run(args).update_todo)
+      when "update-todo"
+        output_result(parse_run(args).update_todo)
+      when "update"
+        output_result(parse_run(args).update_todo)
       when "validate"
         validate(args)
       when nil, "help"

data/lib/packwerk/formatters/offenses_formatter.rb

@@ -26,7 +26,7 @@ module Packwerk
       sig { override.params(offense_collection: Packwerk::OffenseCollection, fileset: T::Set[String]).returns(String) }
       def show_stale_violations(offense_collection, fileset)
         if offense_collection.stale_violations?(fileset)
-          "There were stale violations found, please run `packwerk update-deprecations`"
+          "There were stale violations found, please run `packwerk update-todo`"
         else
           "No stale violations detected"
         end

data/lib/packwerk/offense_collection.rb

@@ -1,6 +1,8 @@
 # typed: strict
 # frozen_string_literal: true
 
+require "pathname"
+
 module Packwerk
   class OffenseCollection
     extend T::Sig
@@ -9,12 +11,12 @@ module Packwerk
     sig do
       params(
         root_path: String,
-        deprecated_references: T::Hash[Packwerk::Package, Packwerk::DeprecatedReferences]
+        package_todo: T::Hash[Packwerk::Package, Packwerk::PackageTodo]
       ).void
     end
-    def initialize(root_path, deprecated_references = {})
+    def initialize(root_path, package_todo = {})
       @root_path = root_path
-      @deprecated_references = T.let(deprecated_references, T::Hash[Packwerk::Package, Packwerk::DeprecatedReferences])
+      @package_todo = T.let(package_todo, T::Hash[Packwerk::Package, Packwerk::PackageTodo])
       @new_violations = T.let([], T::Array[Packwerk::ReferenceOffense])
       @errors = T.let([], T::Array[Packwerk::Offense])
     end
@@ -33,7 +35,7 @@ module Packwerk
       return false unless offense.is_a?(ReferenceOffense)
 
       reference = offense.reference
-      deprecated_references_for(reference.source_package).listed?(reference, violation_type: offense.violation_type)
+      package_todo_for(reference.source_package).listed?(reference, violation_type: offense.violation_type)
     end
 
     sig do
@@ -44,23 +46,23 @@ module Packwerk
         @errors << offense
         return
       end
-      deprecated_references = deprecated_references_for(offense.reference.source_package)
-      unless deprecated_references.add_entries(offense.reference, offense.violation_type)
+      package_todo = package_todo_for(offense.reference.source_package)
+      unless package_todo.add_entries(offense.reference, offense.violation_type)
         new_violations << offense
       end
     end
 
     sig { params(for_files: T::Set[String]).returns(T::Boolean) }
     def stale_violations?(for_files)
-      @deprecated_references.values.any? do |deprecated_references|
-        deprecated_references.stale_violations?(for_files)
+      @package_todo.values.any? do |package_todo|
+        package_todo.stale_violations?(for_files)
       end
     end
 
     sig { params(package_set: Packwerk::PackageSet).void }
-    def persist_deprecated_references_files(package_set)
-      dump_deprecated_references_files
-      cleanup_extra_deprecated_references_files(package_set)
+    def persist_package_todo_files(package_set)
+      dump_package_todo_files
+      cleanup_extra_package_todo_files(package_set)
     end
 
     sig { returns(T::Array[Packwerk::Offense]) }
@@ -68,36 +70,46 @@ module Packwerk
       errors + new_violations
     end
 
+    sig { void }
+    def dump_package_todo_files
+      @package_todo.each_value(&:dump)
+    end
+
     private
 
     sig { params(package_set: Packwerk::PackageSet).void }
-    def cleanup_extra_deprecated_references_files(package_set)
-      packages_without_todos = (package_set.packages.values - @deprecated_references.keys)
+    def cleanup_extra_package_todo_files(package_set)
+      packages_without_todos = (package_set.packages.values - @package_todo.keys)
 
       packages_without_todos.each do |package|
-        Packwerk::DeprecatedReferences.new(
+        Packwerk::PackageTodo.new(
           package,
-          deprecated_references_file_for(package),
+          package_todo_file_for(package),
         ).delete_if_exists
       end
     end
 
-    sig { void }
-    def dump_deprecated_references_files
-      @deprecated_references.each_value(&:dump)
-    end
-
-    sig { params(package: Packwerk::Package).returns(Packwerk::DeprecatedReferences) }
-    def deprecated_references_for(package)
-      @deprecated_references[package] ||= Packwerk::DeprecatedReferences.new(
+    sig { params(package: Packwerk::Package).returns(Packwerk::PackageTodo) }
+    def package_todo_for(package)
+      @package_todo[package] ||= Packwerk::PackageTodo.new(
         package,
-        deprecated_references_file_for(package),
+        package_todo_file_for(package),
       )
     end
 
     sig { params(package: Packwerk::Package).returns(String) }
-    def deprecated_references_file_for(package)
-      File.join(@root_path, package.name, "deprecated_references.yml")
+    def package_todo_file_for(package)
+      if Pathname.new(@root_path).join(package.name, "deprecated_references.yml").exist?
+        warning = <<~WARNING.squish
+          DEPRECATION WARNING: `deprecated_references.yml` files have been renamed to `package_todo.yml`.
+          Run `packwerk update-todo` to rename files automatically.
+        WARNING
+
+        warn(warning)
+        File.join(@root_path, package.name, "deprecated_references.yml")
+      else
+        File.join(@root_path, package.name, "package_todo.yml")
+      end
     end
   end
 end

data/lib/packwerk/{deprecated_references.rb → package_todo.rb}

@@ -4,7 +4,7 @@
 require "yaml"
 
 module Packwerk
-  class DeprecatedReferences
+  class PackageTodo
     extend T::Sig
 
     EntriesType = T.type_alias do
@@ -16,7 +16,7 @@ module Packwerk
       @package = package
       @filepath = filepath
       @new_entries = T.let({}, EntriesType)
-      @deprecated_references = T.let(nil, T.nilable(EntriesType))
+      @todo_list = T.let(nil, T.nilable(EntriesType))
     end
 
     sig do
@@ -24,7 +24,7 @@ module Packwerk
         .returns(T::Boolean)
     end
     def listed?(reference, violation_type:)
-      violated_constants_found = deprecated_references.dig(reference.constant.package.name, reference.constant.name)
+      violated_constants_found = todo_list.dig(reference.constant.package.name, reference.constant.name)
       return false unless violated_constants_found
 
       violated_constant_in_file = violated_constants_found.fetch("files", []).include?(reference.relative_path)
@@ -52,7 +52,7 @@ module Packwerk
     def stale_violations?(for_files)
       prepare_entries_for_dump
 
-      deprecated_references.any? do |package, package_violations|
+      todo_list.any? do |package, package_violations|
         package_violations_for_files = {}
         package_violations.each do |constant_name, entries_for_constant|
           entries_for_files = for_files & entries_for_constant["files"]
@@ -83,6 +83,8 @@ module Packwerk
 
     sig { void }
     def dump
+      delete_old_deprecated_references
+
       if @new_entries.empty?
         delete_if_exists
       else
@@ -93,9 +95,11 @@ module Packwerk
           #
           # You can regenerate this file using the following command:
           #
-          # bin/packwerk update-deprecations #{@package.name}
+          # bin/packwerk update-todo #{@package.name}
         MESSAGE
-        File.open(@filepath, "w") do |f|
+        package_todo_filepath = File.join(File.dirname(@filepath), "package_todo.yml")
+
+        File.open(package_todo_filepath, "w") do |f|
           f.write(message)
           f.write(@new_entries.to_yaml)
         end
@@ -109,6 +113,12 @@ module Packwerk
 
     private
 
+    sig { void }
+    def delete_old_deprecated_references
+      deprecated_references_filepath = File.join(File.dirname(@filepath), "deprecated_references.yml")
+      File.delete(deprecated_references_filepath) if File.exist?(deprecated_references_filepath)
+    end
+
     sig { returns(EntriesType) }
     def prepare_entries_for_dump
       @new_entries.each do |package_name, package_violations|
@@ -123,8 +133,8 @@ module Packwerk
     end
 
     sig { returns(EntriesType) }
-    def deprecated_references
-      @deprecated_references ||= if File.exist?(@filepath)
+    def todo_list
+      @todo_list ||= if File.exist?(@filepath)
         load_yaml(@filepath)
       else
         {}

data/lib/packwerk/parse_run.rb

@@ -49,14 +49,14 @@ module Packwerk
     end
 
     sig { returns(Result) }
-    def update_deprecations
+    def update_todo
       run_context = Packwerk::RunContext.from_configuration(@configuration)
       offense_collection = find_offenses(run_context)
-      offense_collection.persist_deprecated_references_files(run_context.package_set)
+      offense_collection.persist_package_todo_files(run_context.package_set)
 
       message = <<~EOS
         #{@offenses_formatter.show_offenses(offense_collection.errors)}
-        ✅ `deprecated_references.yml` has been updated.
+        ✅ `package_todo.yml` has been updated.
       EOS
 
       Result.new(message: message, status: offense_collection.errors.empty?)

data/lib/packwerk/version.rb

@@ -2,5 +2,5 @@
 # frozen_string_literal: true
 
 module Packwerk
-  VERSION = "2.2.2"
+  VERSION = "2.3.0"
 end

data/lib/packwerk.rb

@@ -21,7 +21,7 @@ module Packwerk
   autoload :ConstantDiscovery
   autoload :ConstantNameInspector
   autoload :ConstNodeInspector
-  autoload :DeprecatedReferences
+  autoload :PackageTodo
   autoload :FileProcessor
   autoload :FilesForProcessing
   autoload :Graph

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: packwerk
 version: !ruby/object:Gem::Version
-  version: 2.2.2
+  version: 2.3.0
 platform: ruby
 authors:
 - Shopify Inc.
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2022-11-15 00:00:00.000000000 Z
+date: 2023-02-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -188,7 +188,6 @@ files:
 - lib/packwerk/const_node_inspector.rb
 - lib/packwerk/constant_discovery.rb
 - lib/packwerk/constant_name_inspector.rb
-- lib/packwerk/deprecated_references.rb
 - lib/packwerk/file_processor.rb
 - lib/packwerk/files_for_processing.rb
 - lib/packwerk/formatters/offenses_formatter.rb
@@ -211,6 +210,7 @@ files:
 - lib/packwerk/output_styles/plain.rb
 - lib/packwerk/package.rb
 - lib/packwerk/package_set.rb
+- lib/packwerk/package_todo.rb
 - lib/packwerk/parse_run.rb
 - lib/packwerk/parsed_constant_definitions.rb
 - lib/packwerk/parsers.rb