Merge pull request #144 from Shopify/add-comments

lib/packwerk/application_load_paths.rb

@@ -4,6 +4,7 @@
 require "bundler"
 
 module Packwerk
+  # Extracts the load paths from the analyzed application so that we can map constant names to paths.
   module ApplicationLoadPaths
     class << self
       extend T::Sig

lib/packwerk/application_validator.rb

@@ -7,6 +7,8 @@
 require "yaml"
 
 module Packwerk
+  # Checks the structure of the application and its packwerk configuration to make sure we can run a check and deliver
+  # correct results.
   class ApplicationValidator
     def initialize(config_file_path:, configuration:, environment:)
       @config_file_path = config_file_path

lib/packwerk/cli.rb

@@ -2,6 +2,7 @@
 # frozen_string_literal: true
 
 module Packwerk
+  # A command-line interface to Packwerk.
   class Cli
     extend T::Sig
 

lib/packwerk/const_node_inspector.rb

@@ -15,6 +15,9 @@ class ConstNodeInspector
     def constant_name_from_node(node, ancestors:)
       return nil unless Node.constant?(node)
       parent = ancestors.first
+
+      # 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`.
       return nil unless root_constant?(parent)
 
       if parent && constant_in_module_or_class_definition?(node, parent: parent)
@@ -30,8 +33,6 @@ def constant_name_from_node(node, ancestors:)
 
     private
 
-    # 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`.
     sig { params(parent: T.nilable(AST::Node)).returns(T::Boolean) }
     def root_constant?(parent)
       !(parent && Node.constant?(parent))

lib/packwerk/constant_name_inspector.rb

@@ -4,7 +4,7 @@
 require "ast"
 
 module Packwerk
-  # An interface describing some object that can extract a constant name from an AST node
+  # An interface describing an object that can extract a constant name from an AST node.
   module ConstantNameInspector
     extend T::Sig
     extend T::Helpers

lib/packwerk/graph.rb

@@ -2,7 +2,9 @@
 # frozen_string_literal: true
 
 module Packwerk
+  # A general implementation of a graph data structure with the ability to check for - and list - cycles.
   class Graph
+    # @param [Array<Array>] edges The edges of the graph; An edge being represented as an Array of two nodes.
     def initialize(*edges)
       @edges = edges.uniq
       @cycles = Set.new

lib/packwerk/inflector.rb

@@ -4,6 +4,7 @@
 require "active_support/inflector"
 
 module Packwerk
+  # A custom inflector used, among other things, to map between constant names and file names.
   class Inflector
     class << self
       extend T::Sig

lib/packwerk/node.rb

@@ -5,6 +5,7 @@
 require "parser/ast/node"
 
 module Packwerk
+  # Convenience methods for working with AST nodes.
   module Node
     class TypeError < ArgumentError; end
     Location = Struct.new(:line, :column)

lib/packwerk/node_processor.rb

@@ -2,6 +2,7 @@
 # frozen_string_literal: true
 
 module Packwerk
+  # Processes a single node in an abstract syntax tree (AST) using the provided checkers.
   class NodeProcessor
     extend T::Sig
 

lib/packwerk/node_visitor.rb

@@ -2,6 +2,7 @@
 # frozen_string_literal: true
 
 module Packwerk
+  # Visits all nodes of an AST, processing them using a given node processor.
   class NodeVisitor
     def initialize(node_processor:)
       @node_processor = node_processor

lib/packwerk/package.rb

@@ -2,6 +2,9 @@
 # frozen_string_literal: true
 
 module Packwerk
+  # The basic unit of modularity for packwerk; a folder that has been declared to define a package.
+  # The package contains all constants defined in files in this folder and all subfolders that are not packages
+  # themselves.
   class Package
     include Comparable
 

lib/packwerk/package_set.rb

@@ -4,6 +4,7 @@
 require "pathname"
 
 module Packwerk
+  # A set of {Packwerk::Package}s as well as methods to parse packages from the filesystem.
   class PackageSet
     include Enumerable
 

lib/packwerk/parsed_constant_definitions.rb

@@ -4,6 +4,7 @@
 require "ast/node"
 
 module Packwerk
+  # A collection of constant definitions parsed from an Abstract Syntax Tree (AST).
   class ParsedConstantDefinitions
     def initialize(root_node:)
       @local_definitions = {}

lib/packwerk/reference.rb

@@ -2,5 +2,6 @@
 # frozen_string_literal: true
 
 module Packwerk
+  # A reference from a file in one package to a constant that may be defined in a different package.
   Reference = Struct.new(:source_package, :relative_path, :constant, :source_location)
 end

lib/packwerk/reference_checking/checkers/dependency_checker.rb

@@ -4,6 +4,7 @@
 module Packwerk
   module ReferenceChecking
     module Checkers
+      # Checks whether a given reference conforms to the configured graph of dependencies.
       class DependencyChecker
         extend T::Sig
         include Checker

lib/packwerk/reference_checking/checkers/privacy_checker.rb

@@ -4,6 +4,7 @@
 module Packwerk
   module ReferenceChecking
     module Checkers
+      # Checks whether a given reference references a private constant of another package.
       class PrivacyChecker
         extend T::Sig
         include Checker

lib/packwerk/reference_extractor.rb

@@ -2,7 +2,7 @@
 # frozen_string_literal: true
 
 module Packwerk
-  # extracts a possible constant reference from a given AST node
+  # Extracts a possible constant reference from a given AST node.
   class ReferenceExtractor
     extend T::Sig
 

lib/packwerk/reference_offense.rb

@@ -2,6 +2,7 @@
 # frozen_string_literal: true
 
 module Packwerk
+  # An offense related to a {Packwerk::Reference}.
   class ReferenceOffense < Offense
     extend T::Sig
     extend T::Helpers

lib/packwerk/run_context.rb

@@ -4,6 +4,7 @@
 require "constant_resolver"
 
 module Packwerk
+  # Holds the context of a Packwerk run across multiple files.
   class RunContext
     extend T::Sig