packwerk 1.0.0

data/lib/packwerk/cli.rb

@@ -0,0 +1,238 @@
+# typed: true
+# frozen_string_literal: true
+require "benchmark"
+require "sorbet-runtime"
+
+require "packwerk/application_validator"
+require "packwerk/configuration"
+require "packwerk/files_for_processing"
+require "packwerk/formatters/progress_formatter"
+require "packwerk/inflector"
+require "packwerk/output_styles"
+require "packwerk/run_context"
+require "packwerk/updating_deprecated_references"
+
+module Packwerk
+  class Cli
+    extend T::Sig
+
+    def initialize(run_context: nil, configuration: nil, out: $stdout, err_out: $stderr, style: OutputStyles::Plain)
+      @out = out
+      @err_out = err_out
+      @style = style
+      @configuration = configuration || Configuration.from_path
+      @run_context = run_context || Packwerk::RunContext.from_configuration(@configuration)
+      @progress_formatter = Formatters::ProgressFormatter.new(@out, style: style)
+    end
+
+    sig { params(args: T::Array[String]).returns(T.noreturn) }
+    def run(args)
+      success = execute_command(args)
+      exit(success)
+    end
+
+    sig { params(args: T::Array[String]).returns(T::Boolean) }
+    def execute_command(args)
+      subcommand = args.shift
+      case subcommand
+      when "init"
+        init
+      when "generate_configs"
+        generate_configs
+      when "check"
+        check(args)
+      when "update"
+        update(args)
+      when "validate"
+        validate(args)
+      when nil, "help"
+        @err_out.puts(<<~USAGE)
+          Usage: #{$PROGRAM_NAME} <subcommand>
+
+          Subcommands:
+            init - set up packwerk
+            check - run all checks
+            update - update deprecated references
+            validate - verify integrity of packwerk and package configuration
+            help  - display help information about packwerk
+        USAGE
+        true
+      else
+        @err_out.puts("'#{subcommand}' is not a packwerk command. See `packwerk help`.")
+        false
+      end
+    end
+
+    private
+
+    def init
+      @out.puts("📦 Initializing Packwerk...")
+
+      application_validation = Packwerk::Generators::ApplicationValidation.generate(
+        for_rails_app: rails_app?,
+        root: @configuration.root_path,
+        out: @out
+      )
+
+      if application_validation
+        if rails_app?
+          # To run in the same space as the Rails process,
+          # in order to fetch load paths for the configuration generator
+          exec("bin/packwerk", "generate_configs")
+        else
+          generate_configurations = generate_configs
+        end
+      end
+
+      application_validation && generate_configurations
+    end
+
+    def generate_configs
+      configuration_file = Packwerk::Generators::ConfigurationFile.generate(
+        load_paths: @configuration.load_paths,
+        root: @configuration.root_path,
+        out: @out
+      )
+      inflections_file = Packwerk::Generators::InflectionsFile.generate(root: @configuration.root_path, out: @out)
+      root_package = Packwerk::Generators::RootPackage.generate(root: @configuration.root_path, out: @out)
+
+      success = configuration_file && inflections_file && root_package
+
+      result = if success
+        <<~EOS
+
+          🎉 Packwerk is ready to be used. You can start defining packages and run `packwerk check`.
+          For more information on how to use Packwerk, see: https://github.com/Shopify/packwerk/blob/main/USAGE.md
+        EOS
+      else
+        <<~EOS
+
+          ⚠️  Packwerk is not ready to be used.
+          Please check output and refer to https://github.com/Shopify/packwerk/blob/main/USAGE.md for more information.
+        EOS
+      end
+
+      @out.puts(result)
+      success
+    end
+
+    def update(paths)
+      updating_deprecated_references = ::Packwerk::UpdatingDeprecatedReferences.new(@configuration.root_path)
+      @run_context = Packwerk::RunContext.from_configuration(
+        @configuration,
+        reference_lister: updating_deprecated_references
+      )
+
+      files = fetch_files_to_process(paths)
+
+      @progress_formatter.started(files)
+
+      all_offenses = T.let([], T.untyped)
+      execution_time = Benchmark.realtime do
+        all_offenses = files.flat_map do |path|
+          @run_context.file_processor.call(path).tap { |offenses| mark_progress(offenses) }
+        end
+
+        updating_deprecated_references.dump_deprecated_references_files
+      end
+
+      @out.puts # put a new line after the progress dots
+      show_offenses(all_offenses)
+      @progress_formatter.finished(execution_time)
+      @out.puts("✅ `deprecated_references.yml` has been updated.")
+
+      all_offenses.empty?
+    end
+
+    def check(paths)
+      files = fetch_files_to_process(paths)
+
+      @progress_formatter.started(files)
+
+      all_offenses = T.let([], T.untyped)
+      execution_time = Benchmark.realtime do
+        files.each do |path|
+          @run_context.file_processor.call(path).tap do |offenses|
+            mark_progress(offenses)
+            all_offenses.concat(offenses)
+          end
+        end
+      rescue Interrupt
+        @out.puts
+        @out.puts("Manually interrupted. Violations caught so far are listed below:")
+      end
+
+      @out.puts # put a new line after the progress dots
+      show_offenses(all_offenses)
+      @progress_formatter.finished(execution_time)
+
+      all_offenses.empty?
+    end
+
+    def fetch_files_to_process(paths)
+      files = FilesForProcessing.fetch(paths: paths, configuration: @configuration)
+      abort("No files found or given. "\
+        "Specify files or check the include and exclude glob in the config file.") if files.empty?
+      files
+    end
+
+    def mark_progress(offenses)
+      if offenses.empty?
+        @progress_formatter.mark_as_inspected
+      else
+        @progress_formatter.mark_as_failed
+      end
+    end
+
+    def validate(_paths)
+      warn("`packwerk validate` should be run within the application. "\
+        "Generate the bin script using `packwerk init` and"\
+        " use `bin/packwerk validate` instead.") unless defined?(::Rails)
+
+      @progress_formatter.started_validation do
+        checker = Packwerk::ApplicationValidator.new(
+          config_file_path: @configuration.config_path,
+          application_load_paths: @configuration.all_application_autoload_paths,
+          configuration: @configuration
+        )
+        result = checker.check_all
+
+        list_validation_errors(result)
+
+        return result.ok?
+      end
+    end
+
+    def show_offenses(offenses)
+      if offenses.empty?
+        @out.puts("No offenses detected 🎉")
+      else
+        offenses.each do |offense|
+          @out.puts(offense.to_s(@style))
+        end
+
+        offenses_string = Inflector.default.pluralize("offense", offenses.length)
+        @out.puts("#{offenses.length} #{offenses_string} detected")
+      end
+    end
+
+    def list_validation_errors(result)
+      @out.puts
+      if result.ok?
+        @out.puts("Validation successful 🎉")
+      else
+        @out.puts("Validation failed ❗")
+        @out.puts(result.error_value)
+      end
+    end
+
+    sig { returns(T::Boolean) }
+    def rails_app?
+      if File.exist?("config/application.rb") && File.exist?("bin/rails")
+        File.foreach("Gemfile").any? { |line| line.match?(/['"]rails['"]/) }
+      else
+        false
+      end
+    end
+  end
+end

data/lib/packwerk/configuration.rb

@@ -0,0 +1,82 @@
+# typed: true
+# frozen_string_literal: true
+
+require "pathname"
+require "yaml"
+
+module Packwerk
+  class Configuration
+    class << self
+      def from_path(path = Dir.pwd)
+        raise ArgumentError, "#{File.expand_path(path)} does not exist" unless File.exist?(path)
+
+        default_packwerk_path = File.join(path, DEFAULT_CONFIG_PATH)
+
+        if File.file?(default_packwerk_path)
+          from_packwerk_config(default_packwerk_path)
+        else
+          new
+        end
+      end
+
+      private
+
+      def from_packwerk_config(path)
+        new(YAML.load_file(path), config_path: path)
+      end
+    end
+
+    DEFAULT_CONFIG_PATH = "packwerk.yml"
+    DEFAULT_INCLUDE_GLOBS = ["**/*.{rb,rake,erb}"]
+    DEFAULT_EXCLUDE_GLOBS = ["{bin,node_modules,script,tmp}/**/*"]
+
+    attr_reader(
+      :include, :exclude, :root_path, :package_paths, :custom_associations, :load_paths, :inflections_file,
+      :config_path,
+    )
+
+    def initialize(configs = {}, config_path: nil)
+      @include = configs["include"] || DEFAULT_INCLUDE_GLOBS
+      @exclude = configs["exclude"] || DEFAULT_EXCLUDE_GLOBS
+      root = config_path ? File.dirname(config_path) : "."
+      @root_path = File.expand_path(root)
+      @package_paths = configs["package_paths"] || "**/"
+      @custom_associations = configs["custom_associations"] || []
+      @load_paths = configs["load_paths"] || all_application_autoload_paths
+      @inflections_file = File.expand_path(configs["inflections_file"] || "config/inflections.yml", @root_path)
+
+      @config_path = config_path
+    end
+
+    def all_application_autoload_paths
+      return [] unless defined?(::Rails)
+
+      all_paths = Rails.application.railties
+        .select { |railtie| railtie.is_a?(Rails::Engine) }
+        .push(Rails.application)
+        .flat_map do |engine|
+        (engine.config.autoload_paths + engine.config.eager_load_paths + engine.config.autoload_once_paths).uniq
+      end
+
+      all_paths = all_paths.map do |path_string|
+        # ignore paths outside of the Rails root
+        path = Pathname.new(path_string)
+        if path.exist? && path.realpath.fnmatch(Rails.root.join("**").to_s)
+          path.relative_path_from(Rails.root).to_s
+        end
+      end
+
+      all_paths.compact.tap do |paths|
+        if paths.empty?
+          raise <<~EOS
+            No autoload paths have been set up in your Rails app. This is likely a bug, and
+            packwerk is unlikely to work correctly without any autoload paths.
+
+            You can follow the Rails guides on setting up load paths, or manually configure
+            them in `packwerk.yml` with `load_paths`.
+          EOS
+        end
+      end
+    end
+  end
+end

data/lib/packwerk/const_node_inspector.rb

@@ -0,0 +1,44 @@
+# typed: true
+# frozen_string_literal: true
+
+require "packwerk/constant_name_inspector"
+
+module Packwerk
+  # Extracts a constant name from an AST node of type :const
+  class ConstNodeInspector
+    include ConstantNameInspector
+
+    def constant_name_from_node(node, ancestors:)
+      return nil unless Node.type(node) == Node::CONSTANT
+
+      # Only process the root `const` node for namespaced constant references. For example, in the
+      # reference `Spam::Eggs::Thing`, we only process the const node associated with `Spam`.
+      parent = ancestors.first
+      return nil if parent && Node.type(parent) == Node::CONSTANT
+
+      if constant_in_module_or_class_definition?(node, parent: parent)
+        # We're defining a class with this name, in which case the constant is implicitly fully qualified by its
+        # enclosing namespace
+        name = Node.parent_module_name(ancestors: ancestors)
+        name ||= Node.enclosing_namespace_path(node, ancestors: ancestors).push(Node.constant_name(node)).join("::")
+
+        "::" + name
+      else
+        begin
+          Node.constant_name(node)
+        rescue Node::TypeError
+          nil
+        end
+      end
+    end
+
+    private
+
+    def constant_in_module_or_class_definition?(node, parent:)
+      if parent
+        parent_name = Node.module_name_from_definition(parent)
+        parent_name && parent_name == Node.constant_name(node)
+      end
+    end
+  end
+end

data/lib/packwerk/constant_discovery.rb

@@ -0,0 +1,60 @@
+# typed: true
+# frozen_string_literal: true
+
+module Packwerk
+  # Get information about (partially qualified) constants without loading the application code.
+  # Information gathered: Fully qualified name, path to file containing the definition, package,
+  # and visibility (public/private to the package).
+  #
+  # The implementation makes a few assumptions about the code base:
+  # - `Something::SomeOtherThing` is defined in a path of either `something/some_other_thing.rb` or `something.rb`,
+  #   relative to the load path. Rails' `zeitwerk` autoloader makes the same assumption.
+  # - It is OK to not always infer the exact file defining the constant. For example, when a constant is inherited, we
+  #   have no way of inferring the file it is defined in. You could argue though that inheritance means that another
+  #   constant with the same name exists in the inheriting class, and this view is sufficient for all our use cases.
+  class ConstantDiscovery
+    ConstantContext = Struct.new(:name, :location, :package, :public?)
+
+    # @param constant_resolver [ConstantResolver]
+    # @param packages [Packwerk::PackageSet]
+    def initialize(constant_resolver:, packages:)
+      @packages = packages
+      @resolver = constant_resolver
+    end
+
+    # Get the package that owns a given file path.
+    #
+    # @param path [String] the file path
+    #
+    # @return [Packwerk::Package] the package that contains the given file,
+    #   or nil if the path is not owned by any component
+    def package_from_path(path)
+      @packages.package_from_path(path)
+    end
+
+    # Analyze a constant via its name.
+    # If the name is partially qualified, we need the current namespace path to correctly infer its full name
+    #
+    # @param const_name [String] The constant's name, fully or partially qualified.
+    # @param current_namespace_path [Array<String>] (optional) The namespace of the context in which the constant is
+    #   used, e.g. ["Apps", "Models"] for `Apps::Models`. Defaults to [] which means top level.
+    # @return [Packwerk::ConstantDiscovery::ConstantContext]
+    def context_for(const_name, current_namespace_path: [])
+      begin
+        constant = @resolver.resolve(const_name, current_namespace_path: current_namespace_path)
+      rescue ConstantResolver::Error => e
+        raise(ConstantResolver::Error, e.message + "\n Make sure autoload paths are added to the config file.")
+      end
+
+      return unless constant
+
+      package = @packages.package_from_path(constant.location)
+      ConstantContext.new(
+        constant.name,
+        constant.location,
+        package,
+        package&.public_path?(constant.location),
+      )
+    end
+  end
+end

data/lib/packwerk/constant_name_inspector.rb

@@ -0,0 +1,22 @@
+# typed: true
+# frozen_string_literal: true
+
+require "ast"
+require "sorbet-runtime"
+
+module Packwerk
+  # An interface describing some object that can extract a constant name from an AST node
+  module ConstantNameInspector
+    extend T::Sig
+    extend T::Helpers
+
+    interface!
+
+    sig do
+      params(node: ::AST::Node, ancestors: T::Array[::AST::Node])
+        .returns(T.nilable(String))
+        .abstract
+    end
+    def constant_name_from_node(node, ancestors:); end
+  end
+end