pinspec 0.1.0 → 0.3.0

data/lib/pinspec/analyzer/target_parser.rb

@@ -19,13 +19,26 @@ module Pinspec
 
       VISIBILITIES = %i[public private protected].freeze
 
-      SCALARISH_NAMES = %w[
-        amount total subtotal price cost quantity qty count index number num
-        name email phone title body text message description reason code type
-        kind status state value key data payload options opts args params attrs
-        attributes config settings id token flag mode format scope limit offset
-        date time now today percent rate ratio sum size length label url path
-      ].freeze
+      # Names that are a bag of attributes rather than a model. `create_params`,
+      # `options`, `article_attributes`.
+      HASH_SHAPED = /\A(?:\w+_)?(?:params|options|attributes|attrs|opts)\z/
+
+      # These names are not models - but saying only that leaves the corpus with no
+      # value at all, and a required parameter then receives an invented nil. The
+      # target raises on it and pinspec pins that error as the application's
+      # behaviour, which is the one thing it promises never to do. So each name maps
+      # to a type the corpus can actually build.
+      SCALARISH_TYPES = {
+        "String" => %w[
+          name email phone title body text message description reason code key
+          path url slug token label format mode scope type kind status state
+          value data
+        ],
+        "Integer" => %w[count index number num limit offset size length quantity qty position],
+        "Float" => %w[amount total subtotal price cost percent rate ratio sum]
+      }.freeze
+
+      SCALARISH_NAMES = SCALARISH_TYPES.values.flatten.freeze
 
       DI_PATTERNS = [
         /\ARails\.application\.config\b/,
@@ -60,18 +73,48 @@ module Pinspec
           new(file_path, method_name).parse
         end
 
+        # Returns [file, method] with method nil when the target named none. It is
+        # the caller's job to discover one, because that needs the file's contents
+        # and the surrounding directory's convention.
         def split_target(target)
-          unless target.to_s.include?("#")
+          text = target.to_s
+          return text.split("#", 2) if text.include?("#")
+
+          unless text.end_with?(".rb")
             raise ArgumentError,
-                  "target must be FILE#METHOD (got #{target.inspect}); " \
-                  "e.g. app/services/invoice_calculator.rb#call"
+                  "target must be a Ruby file, optionally with #METHOD " \
+                  "(got #{target.inspect}); e.g. app/services/invoice_calculator.rb#call"
           end
 
-          target.split("#", 2)
+          [text, nil]
         end
       end
 
-      def initialize(file_path, method_name)
+      class << self
+        # Keyed by application root, because a batch run builds one parser per file
+        # and re-globbing the application for each would be quadratic.
+        def application_sources_for(root)
+          @application_sources ||= {}
+          @application_sources[root] ||= begin
+            dirs = %w[app lib].map { |d| File.join(root, d) }.select { |d| File.directory?(d) }
+            dirs.flat_map { |dir| Dir.glob(File.join(dir, "**", "*.rb")) }.sort
+          end
+        end
+
+        def application_scope_cache(root)
+          @application_scopes ||= {}
+          @application_scopes[root] ||= {}
+        end
+
+        # Tests and long-lived processes need a way back to a clean slate.
+        def reset_application_cache!
+          @application_sources = {}
+          @application_scopes = {}
+        end
+      end
+
+      def initialize(file_path, method_name, app_root: nil)
+        @app_root   = app_root
         @file_path  = file_path
         @descriptor = parse_descriptor(method_name)
       end
@@ -108,7 +151,8 @@ module Pinspec
           takes_block:          false,
           source_range:         [mdef.node.location.start_line, mdef.node.location.end_line],
           referenced_constants: referenced_constants(scan),
-          clock_sites:          clock_sites(scan)
+          clock_sites:          clock_sites(scan),
+          construction_source:  @construction_source || :own
         )
       end
 
@@ -387,8 +431,12 @@ module Pinspec
 
       def resolve_construction(scope, mdef)
         return [:class_method, []] if mdef.singleton
+        return [:class_method, []] if module_self_calling?(scope)
         return [:model_instance, []] if model_scope?(scope)
 
+        attr_extras = attr_extras_params(scope)
+        return [:new, attr_extras] if attr_extras
+
         members = struct_members(scope)
         return [:struct, members] if members
 
@@ -404,33 +452,60 @@ module Pinspec
         inherited_construction(scope)
       end
 
+      # A class with no #initialize is not an unreadable constructor - it is the
+      # default one. The commonest shape in real applications is a service that
+      # inherits behaviour and takes its dependencies as method arguments:
+      #
+      #   class FavouriteService < BaseService
+      #     def call(account, status)
+      #
+      # Refusing that cost 88% of one real codebase's service directory. So the
+      # superclass chain is followed through the application, and only a constructor
+      # that EXISTS and cannot be read is refused.
+      MAX_ANCESTOR_HOPS = 4
+
       def inherited_construction(scope)
         sup = scope.superclass_slice
         return [:new, []] if sup.nil? || INERT_BASES.include?(sup)
 
-        parent = resolve_scope_relative(sup, scope)
-        unless parent
-          raise UnresolvableSetup.new(
-            :opaque_constructor,
-            "#{scope.name} inherits from #{sup}, which is not defined in " \
-            "#{@file_path}, and defines no #initialize of its own, so its " \
-            "constructor signature can't be read statically. Give #{scope.name} " \
-            "an explicit #initialize, or pin a class-method entry point."
-          )
-        end
+        params = ancestor_initializer_params(sup, scope)
+        return params if params
 
-        parent_init = find_initialize(parent.name)
-        return [:new, params_of(parent_init)] if parent_init
+        # Nothing in the chain defines one, so `new` takes no arguments. When the
+        # chain left the application the assumption is unverified, and says so.
+        @construction_source = @left_application ? :assumed : :inherited
+        [:new, []]
+      end
 
-        parent_sup = parent.superclass_slice
-        return [:new, []] if parent_sup.nil? || INERT_BASES.include?(parent_sup)
+      # Walks up through the application. Returns [:new, params] when an ancestor
+      # defines #initialize, or nil when none does.
+      def ancestor_initializer_params(name, scope)
+        seen = []
+        current = name
+        hops = 0
 
-        raise UnresolvableSetup.new(
-          :opaque_constructor,
-          "#{scope.name} < #{parent.name} < #{parent_sup}: neither #{scope.name} " \
-          "nor #{parent.name} defines #initialize, and #{parent_sup} is outside " \
-          "#{@file_path}. pinspec resolves one level up only."
-        )
+        while current && hops < MAX_ANCESTOR_HOPS
+          break if INERT_BASES.include?(current) || seen.include?(current)
+
+          seen << current
+          hops += 1
+
+          parent = resolve_scope_relative(current, scope) || scope_from_application(current)
+          if parent.nil?
+            @left_application = true
+            return nil
+          end
+
+          init = find_initialize(parent.name) || initializer_in(parent)
+          if init
+            @construction_source = :inherited
+            return [:new, params_of(init)]
+          end
+
+          current = parent.superclass_slice
+        end
+
+        nil
       end
 
       def guard_opaque_initialize!(scope, init)
@@ -485,6 +560,62 @@ module Pinspec
         MODEL_BASES.include?(sup) || MODEL_BASES.any? { |b| sup.end_with?("::#{b}") }
       end
 
+      # A module that calls `module_function` or `extend self` answers its own methods,
+      # so there is nothing to construct. Calling .new on it raised
+      # "undefined method 'new' for module ..." inside the probe - a setup_error that
+      # named the application rather than the shape pinspec had failed to recognise.
+      def module_self_calling?(scope)
+        return false unless scope.kind == :module
+
+        scope_calls(scope).any? do |call|
+          call.receiver.nil? && %i[module_function extend].include?(call.name) &&
+            (call.name == :module_function || self_argument?(call))
+        end
+      end
+
+      def self_argument?(call)
+        Array(call.arguments&.arguments).any? { |arg| arg.is_a?(Prism::SelfNode) }
+      end
+
+      # attr_extras. `pattr_initialize`/`attr_initialize` generate the constructor, so
+      # a class using one has no `def initialize` to read and looked like it took no
+      # arguments at all - pinspec then called .new with nothing and the generated
+      # constructor raised KeyError. That is 110 of chatwoot's 386 service files.
+      #
+      #   pattr_initialize :account, :params          -> two required positionals
+      #   pattr_initialize [:inbox!, :params!]        -> two required keywords
+      #   pattr_initialize [:channel!, :message]      -> one required, one optional
+      #
+      # A bare symbol is positional; symbols inside an array are keywords, and the
+      # trailing "!" is attr_extras' own mark for "required".
+      ATTR_EXTRAS_MACROS = %i[pattr_initialize attr_initialize].freeze
+
+      def attr_extras_params(scope)
+        call = scope_calls(scope).find do |node|
+          node.receiver.nil? && ATTR_EXTRAS_MACROS.include?(node.name)
+        end
+        return nil if call.nil?
+
+        Array(call.arguments&.arguments).flat_map { |arg| attr_extras_args(arg) }
+      end
+
+      def attr_extras_args(node)
+        case node
+        when Prism::SymbolNode
+          [build_param(node.unescaped.to_sym, :req, nil)]
+        when Prism::ArrayNode
+          node.elements.grep(Prism::SymbolNode).map do |element|
+            name = element.unescaped
+            required = name.end_with?("!")
+
+            build_param(name.delete_suffix("!").to_sym, required ? :keyreq : :key,
+                        required ? nil : "nil")
+          end
+        else
+          []
+        end
+      end
+
       def struct_members(scope)
         node = scope.superclass_node
         return nil unless node.is_a?(Prism::CallNode)
@@ -555,6 +686,110 @@ module Pinspec
         end&.node
       end
 
+      # The superclass usually lives in another file of the same application. Finding
+      # it is a search for `class <Name>` under app/ and lib/, parsed with Prism so a
+      # name inside a comment or a string cannot match.
+      def scope_from_application(name)
+        return nil if application_root.nil?
+
+        cache = self.class.application_scope_cache(application_root)
+        return cache[name] if cache.key?(name)
+
+        cache[name] = find_scope_in_application(name)
+      end
+
+      def find_scope_in_application(name)
+        demodulized = name.split("::").last
+        pattern = /^\s*class\s+(?:[\w:]+::)?#{Regexp.escape(demodulized)}\b/
+
+        application_sources.each do |path|
+          source = Source.read(path)
+          next unless source.match?(pattern)
+
+          result = Prism.parse(source)
+          next unless result.success?
+
+          found = scope_named(result.value, name, demodulized)
+          return found if found
+        end
+
+        nil
+      end
+
+      # Only the files an application owns. A gem's base class is deliberately out of
+      # reach: pinspec would be reading code the application cannot change.
+      def application_sources
+        self.class.application_sources_for(application_root)
+      end
+
+      def application_root
+        return @application_root if defined?(@application_root)
+
+        @application_root = @app_root || infer_application_root
+      end
+
+      # Walk up from the target until something that marks a Rails root appears.
+      def infer_application_root
+        dir = File.dirname(File.expand_path(@file_path))
+
+        while dir != "/" && dir != File.dirname(dir)
+          return dir if File.file?(File.join(dir, "Gemfile")) ||
+                        File.directory?(File.join(dir, "db")) ||
+                        File.file?(File.join(dir, "config", "application.rb"))
+
+          dir = File.dirname(dir)
+        end
+
+        nil
+      end
+
+      def scope_named(root, qualified, demodulized)
+        found = nil
+
+        walk = lambda do |node, prefix|
+          return if found || node.nil?
+
+          if node.is_a?(Prism::ClassNode)
+            name = [prefix, node.constant_path.slice].compact.reject(&:empty?).join("::")
+            if name == qualified || node.constant_path.slice == qualified ||
+               node.constant_path.slice == demodulized
+              found = Scope.new(name: name, node: node, kind: :class,
+                                superclass_slice: node.superclass&.slice,
+                                superclass_node: node.superclass, parent: nil)
+              return
+            end
+            prefix = name
+          elsif node.is_a?(Prism::ModuleNode)
+            prefix = [prefix, node.constant_path.slice].compact.reject(&:empty?).join("::")
+          end
+
+          node.compact_child_nodes.each { |child| walk.call(child, prefix) }
+        end
+
+        walk.call(root, nil)
+        found
+      end
+
+      # An #initialize defined directly in a scope found elsewhere in the application.
+      def initializer_in(scope)
+        return nil unless scope.node.is_a?(Prism::ClassNode)
+
+        found = nil
+        walk = lambda do |node|
+          return if found || node.nil?
+
+          if node.is_a?(Prism::DefNode) && node.name == :initialize && node.receiver.nil?
+            found = node
+            return
+          end
+
+          node.compact_child_nodes.each { |child| walk.call(child) }
+        end
+
+        walk.call(scope.node.body)
+        found
+      end
+
       def resolve_scope_relative(name, scope)
         nesting = scope.name.split("::")
 
@@ -629,7 +864,10 @@ module Pinspec
         return "Array"   if s.end_with?("_ids")
         return "Time"    if s.end_with?("_at")
         return "Date"    if s.end_with?("_on", "_date")
-        return nil if SCALARISH_NAMES.include?(s)
+        return "Hash"    if HASH_SHAPED.match?(s)
+        return "Array"   if s.end_with?("s") && !s.end_with?("ss", "us", "is")
+        scalar = SCALARISH_TYPES.find { |_type, names| names.include?(s) }
+        return scalar.first if scalar
         return nil unless s.match?(/\A[a-z][a-z0-9_]*\z/)
 
         camelize(s)

data/lib/pinspec/batch.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Pinspec
+  class Batch
+    SKIP_PATTERNS = [%r{/concerns/}, %r{_spec\.rb\z}, %r{/spec/}, %r{/test/}].freeze
+
+    Outcome = Data.define(:file, :target, :status, :detail, :pinned, :spec_path) do
+      def pinned?
+        status == :pinned
+      end
+
+      def refused?
+        status == :refused
+      end
+    end
+
+    Report = Data.define(:outcomes) do
+      def pinned
+        outcomes.select(&:pinned?)
+      end
+
+      def refused
+        outcomes.select(&:refused?)
+      end
+
+      def failed
+        outcomes.reject { |outcome| outcome.pinned? || outcome.refused? }
+      end
+
+      def anything_pinned?
+        !pinned.empty?
+      end
+    end
+
+    # Patterns match the path RELATIVE to the directory being pinned. Matching the
+    # absolute path means an app that happens to live under a directory called
+    # `spec` has every one of its files skipped.
+    def self.targets_in(path)
+      return [path] if File.file?(path)
+
+      root = File.expand_path(path)
+
+      Dir.glob(File.join(root, "**", "*.rb")).reject do |file|
+        relative = file.delete_prefix("#{root}/")
+
+        SKIP_PATTERNS.any? { |pattern| "/#{relative}".match?(pattern) }
+      end.sort
+    end
+
+    def initialize(files, &pin)
+      @files = files
+      @pin = pin
+    end
+
+    # A refusal is information, not a stop: one target that takes a block must not
+    # end a run over a directory of forty.
+    def run
+      Report.new(outcomes: @files.map { |file| attempt(file) })
+    end
+
+    private
+
+    def attempt(file)
+      @pin.call(file)
+    rescue UnresolvableSetup, BlockRequired, AmbiguousTarget, TargetNotFound,
+           NothingStableToPin, UnsupportedRailsVersion => e
+      Outcome.new(file: file, target: nil, status: :refused, detail: reason_for(e),
+                  pinned: 0, spec_path: nil)
+    rescue VerifyFailed, ProbeFailure => e
+      Outcome.new(file: file, target: nil, status: :failed, detail: e.message.lines.first.to_s.strip,
+                  pinned: 0, spec_path: nil)
+    end
+
+    def reason_for(error)
+      return "#{error.class.name.split('::').last}(#{error.reason})" if error.respond_to?(:reason)
+
+      error.class.name.split("::").last
+    end
+  end
+end