packwerk 1.0.0

data/lib/packwerk/parsers/ruby.rb

@@ -0,0 +1,42 @@
+# typed: true
+# frozen_string_literal: true
+
+require "parser"
+require "parser/current"
+
+module Packwerk
+  module Parsers
+    class Ruby
+      class RaiseExceptionsParser < Parser::CurrentRuby
+        def initialize(builder)
+          super(builder)
+          super.diagnostics.all_errors_are_fatal = true
+        end
+      end
+
+      class TolerateInvalidUtf8Builder < Parser::Builders::Default
+        def string_value(token)
+          value(token)
+        end
+      end
+
+      def initialize(parser_class: RaiseExceptionsParser)
+        @builder = TolerateInvalidUtf8Builder.new
+        @parser_class = parser_class
+      end
+
+      def call(io:, file_path: "<unknown>")
+        buffer = Parser::Source::Buffer.new(file_path)
+        buffer.source = io.read
+        parser = @parser_class.new(@builder)
+        parser.parse(buffer)
+      rescue EncodingError => e
+        result = ParseResult.new(file: file_path, message: e.message)
+        raise Parsers::ParseError, result
+      rescue Parser::SyntaxError => e
+        result = ParseResult.new(file: file_path, message: "Syntax error: #{e}")
+        raise Parsers::ParseError, result
+      end
+    end
+  end
+end

data/lib/packwerk/privacy_checker.rb

@@ -0,0 +1,45 @@
+# typed: true
+# frozen_string_literal: true
+
+require "packwerk/violation_type"
+
+module Packwerk
+  class PrivacyChecker
+    def violation_type
+      ViolationType::Privacy
+    end
+
+    def invalid_reference?(reference, reference_lister)
+      return if reference.constant.public?
+
+      privacy_option = reference.constant.package.enforce_privacy
+      return if enforcement_disabled?(privacy_option)
+
+      return unless privacy_option == true ||
+        explicitly_private_constant?(reference.constant, explicitly_private_constants: privacy_option)
+
+      return if reference_lister.listed?(reference, violation_type: violation_type)
+
+      true
+    end
+
+    def message_for(reference)
+      source_desc = reference.source_package ? "'#{reference.source_package}'" : "here"
+      "Privacy violation: '#{reference.constant.name}' is private to '#{reference.constant.package}' but " \
+        "referenced from #{source_desc}.\n" \
+        "Is there a public entrypoint in '#{reference.constant.package.public_path}' that you can use instead?"
+    end
+
+    private
+
+    def explicitly_private_constant?(constant, explicitly_private_constants:)
+      explicitly_private_constants.include?(constant.name) ||
+        # nested constants
+        explicitly_private_constants.any? { |epc| constant.name.start_with?(epc + "::") }
+    end
+
+    def enforcement_disabled?(privacy_option)
+      [false, nil].include?(privacy_option)
+    end
+  end
+end

data/lib/packwerk/reference.rb

@@ -0,0 +1,6 @@
+# typed: true
+# frozen_string_literal: true
+
+module Packwerk
+  Reference = Struct.new(:source_package, :relative_path, :constant)
+end

data/lib/packwerk/reference_extractor.rb

@@ -0,0 +1,81 @@
+# typed: true
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+require "packwerk/constant_discovery"
+require "packwerk/constant_name_inspector"
+require "packwerk/node"
+require "packwerk/parsed_constant_definitions"
+require "packwerk/reference"
+
+module Packwerk
+  # extracts a possible constant reference from a given AST node
+  class ReferenceExtractor
+    extend T::Sig
+
+    sig do
+      params(
+        context_provider: Packwerk::ConstantDiscovery,
+        constant_name_inspectors: T::Array[Packwerk::ConstantNameInspector],
+        root_node: ::AST::Node,
+        root_path: String,
+      ).void
+    end
+    def initialize(
+      context_provider:,
+      constant_name_inspectors:,
+      root_node:,
+      root_path:
+    )
+      @context_provider = context_provider
+      @constant_name_inspectors = constant_name_inspectors
+      @root_path = root_path
+      @local_constant_definitions = ParsedConstantDefinitions.new(root_node: root_node)
+    end
+
+    def reference_from_node(node, ancestors:, file_path:)
+      constant_name = T.let(nil, T.nilable(String))
+
+      @constant_name_inspectors.each do |inspector|
+        constant_name = inspector.constant_name_from_node(node, ancestors: ancestors)
+        break if constant_name
+      end
+
+      reference_from_constant(constant_name, node: node, ancestors: ancestors, file_path: file_path) if constant_name
+    end
+
+    private
+
+    def reference_from_constant(constant_name, node:, ancestors:, file_path:)
+      namespace_path = Node.enclosing_namespace_path(node, ancestors: ancestors)
+      return if local_reference?(constant_name, Node.name_location(node), namespace_path)
+
+      constant =
+        @context_provider.context_for(
+          constant_name,
+          current_namespace_path: namespace_path
+        )
+
+      return if constant&.package.nil?
+
+      relative_path =
+        Pathname.new(file_path)
+          .relative_path_from(@root_path).to_s
+
+      source_package = @context_provider.package_from_path(relative_path)
+
+      return if source_package == constant.package
+
+      Reference.new(source_package, relative_path, constant)
+    end
+
+    def local_reference?(constant_name, name_location, namespace_path)
+      @local_constant_definitions.local_reference?(
+        constant_name,
+        location: name_location,
+        namespace_path: namespace_path
+      )
+    end
+  end
+end

data/lib/packwerk/reference_lister.rb

@@ -0,0 +1,23 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+require "packwerk/reference"
+require "packwerk/violation_type"
+
+module Packwerk
+  module ReferenceLister
+    extend T::Sig
+    extend T::Helpers
+
+    interface!
+
+    sig do
+      params(reference: Packwerk::Reference, violation_type: ViolationType)
+        .returns(T::Boolean)
+        .abstract
+    end
+    def listed?(reference, violation_type:); end
+  end
+end

data/lib/packwerk/run_context.rb

@@ -0,0 +1,103 @@
+# typed: true
+# frozen_string_literal: true
+
+require "active_support/inflector"
+require "constant_resolver"
+
+require "packwerk/association_inspector"
+require "packwerk/checking_deprecated_references"
+require "packwerk/constant_discovery"
+require "packwerk/const_node_inspector"
+require "packwerk/dependency_checker"
+require "packwerk/file_processor"
+require "packwerk/node_processor"
+require "packwerk/package_set"
+require "packwerk/privacy_checker"
+require "packwerk/reference_extractor"
+
+module Packwerk
+  class RunContext
+    attr_reader(
+      :checkers,
+      :constant_name_inspectors,
+      :context_provider,
+      :root_path,
+      :file_processor,
+      :node_processor_class,
+      :reference_lister
+    )
+
+    DEFAULT_CHECKERS = [
+      ::Packwerk::DependencyChecker,
+      ::Packwerk::PrivacyChecker,
+    ]
+
+    class << self
+      def from_configuration(configuration, reference_lister: nil)
+        default_reference_lister = reference_lister ||
+          ::Packwerk::CheckingDeprecatedReferences.new(configuration.root_path)
+        new(
+          root_path: configuration.root_path,
+          load_paths: configuration.load_paths,
+          inflector: ActiveSupport::Inflector,
+          custom_associations: configuration.custom_associations,
+          reference_lister: default_reference_lister,
+        )
+      end
+    end
+
+    def initialize(
+      root_path:,
+      load_paths:,
+      package_paths: nil,
+      inflector: nil,
+      custom_associations: [],
+      checker_classes: DEFAULT_CHECKERS,
+      node_processor_class: NodeProcessor,
+      reference_lister: nil
+    )
+      @root_path = File.expand_path(root_path)
+
+      resolver = ConstantResolver.new(
+        root_path: @root_path,
+        load_paths: load_paths,
+        inflector: inflector,
+      )
+
+      package_set = ::Packwerk::PackageSet.load_all_from(@root_path, package_pathspec: package_paths)
+
+      @context_provider = ::Packwerk::ConstantDiscovery.new(
+        constant_resolver: resolver,
+        packages: package_set
+      )
+
+      @reference_lister = reference_lister || ::Packwerk::CheckingDeprecatedReferences.new(@root_path)
+
+      @checkers = checker_classes.map(&:new)
+
+      @constant_name_inspectors = [
+        ::Packwerk::ConstNodeInspector.new,
+        ::Packwerk::AssociationInspector.new(inflector: inflector, custom_associations: custom_associations),
+      ]
+
+      @node_processor_class = node_processor_class
+      @file_processor = FileProcessor.new(run_context: self)
+    end
+
+    def node_processor_for(filename:, ast_node:)
+      reference_extractor = ::Packwerk::ReferenceExtractor.new(
+        context_provider: context_provider,
+        constant_name_inspectors: constant_name_inspectors,
+        root_node: ast_node,
+        root_path: root_path,
+      )
+
+      node_processor_class.new(
+        reference_extractor: reference_extractor,
+        reference_lister: @reference_lister,
+        filename: filename,
+        checkers: checkers,
+      )
+    end
+  end
+end

data/lib/packwerk/sanity_checker.rb

@@ -0,0 +1,10 @@
+# typed: ignore
+# frozen_string_literal: true
+
+require "packwerk/application_validator"
+
+module Packwerk
+  # To do: This alias and file should be removed as it is deprecated
+  warn("DEPRECATION WARNING: Packwerk::SanityChecker is deprecated, use Packwerk::ApplicationValidator instead.")
+  SanityChecker = ApplicationValidator
+end

data/lib/packwerk/spring_command.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+# typed: ignore
+
+require "spring/commands"
+
+module Packwerk
+  class SpringCommand
+    def env(*)
+      # Packwerk needs to run in a test environment, which has a set of autoload paths that are
+      # often a superset of the dev/prod paths (for example, test/support/helpers)
+      "test"
+    end
+
+    def exec_name
+      "packwerk"
+    end
+
+    def gem_name
+      "packwerk"
+    end
+
+    def call
+      load(Gem.bin_path(gem_name, exec_name))
+    end
+  end
+
+  Spring.register_command("packwerk", SpringCommand.new)
+end

data/lib/packwerk/updating_deprecated_references.rb

@@ -0,0 +1,51 @@
+# typed: true
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+require "packwerk/deprecated_references"
+require "packwerk/reference"
+require "packwerk/reference_lister"
+require "packwerk/violation_type"
+
+module Packwerk
+  class UpdatingDeprecatedReferences
+    extend T::Sig
+    include ReferenceLister
+
+    def initialize(root_path, deprecated_references = {})
+      @root_path = root_path
+      @deprecated_references = deprecated_references
+    end
+
+    sig do
+      params(reference: Packwerk::Reference, violation_type: ViolationType)
+        .returns(T::Boolean)
+        .override
+    end
+    def listed?(reference, violation_type:)
+      deprecated_references = deprecated_references_for(reference.source_package)
+      deprecated_references.add_entries(reference, violation_type.serialize)
+      true
+    end
+
+    def dump_deprecated_references_files
+      @deprecated_references.each do |_, deprecated_references_file|
+        deprecated_references_file.dump
+      end
+    end
+
+    private
+
+    def deprecated_references_for(package)
+      @deprecated_references[package] ||= Packwerk::DeprecatedReferences.new(
+        package,
+        deprecated_references_file_for(package),
+      )
+    end
+
+    def deprecated_references_file_for(package)
+      File.join(@root_path, package.name, "deprecated_references.yml")
+    end
+  end
+end

data/lib/packwerk/version.rb

@@ -0,0 +1,6 @@
+# typed: strong
+# frozen_string_literal: true
+
+module Packwerk
+  VERSION = "1.0.0"
+end

data/lib/packwerk/violation_type.rb

@@ -0,0 +1,13 @@
+# typed: true
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+module Packwerk
+  class ViolationType < T::Enum
+    enums do
+      Privacy = new
+      Dependency = new
+    end
+  end
+end

data/library.yml

@@ -0,0 +1,6 @@
+---
+name: Packwerk
+stewards:
+- "@Shopify/kernel-architecture-patterns"
+slack_channels:
+- architecture-patterns

data/packwerk.gemspec

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require_relative "lib/packwerk/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "packwerk"
+  spec.version       = Packwerk::VERSION
+  spec.authors       = ["Shopify Inc."]
+  spec.email         = ["gems@shopify.com"]
+
+  spec.summary       = "Packages for applications based on the zeitwerk autoloader"
+
+  spec.description   = <<~DESCRIPTION
+    Sets package level boundaries between a specified set of ruby
+    constants to minimize cross-boundary referencing and dependency.
+  DESCRIPTION
+  spec.homepage      = "https://github.com/Shopify/packwerk"
+  spec.license       = "MIT"
+
+  if spec.respond_to?(:metadata)
+    spec.metadata["homepage_uri"] = spec.homepage
+    spec.metadata["source_code_uri"] = "https://github.com/Shopify/packwerk"
+    spec.metadata["changelog_uri"] = "https://github.com/Shopify/packwerk/releases"
+  end
+
+  if spec.respond_to?(:metadata)
+    spec.metadata["allowed_push_host"] = "https://rubygems.org"
+  else
+    raise "RubyGems 2.0 or newer is required to protect against " \
+      "public gem pushes."
+  end
+
+  spec.bindir = "exe"
+  spec.executables << "packwerk"
+
+  spec.files = Dir.chdir(File.expand_path("..", __FILE__)) do
+    %x(git ls-files -z).split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.require_paths = %w(lib)
+
+  spec.required_ruby_version = ">= 2.6"
+
+  spec.add_dependency("activesupport", ">= 5.2")
+  spec.add_dependency("constant_resolver")
+  spec.add_dependency("sorbet-runtime")
+
+  spec.add_development_dependency("bundler")
+  spec.add_development_dependency("rake")
+  spec.add_development_dependency("sorbet")
+  spec.add_development_dependency("m")
+
+  # For Ruby parsing
+  spec.add_dependency("ast")
+  spec.add_dependency("parser")
+
+  # For ERB parsing
+  spec.add_dependency("better_html")
+end