crap4ruby 0.1.0 → 0.2.0

data/lib/crap4ruby/analyzer.rb

@@ -1,7 +1,32 @@
 # frozen_string_literal: true
 
 module Crap4Ruby
+  # Finds explicit methods and literal define_method blocks without executing code.
   class Analyzer
+    # RuboCop 1.92.1 Metrics::Utils::IteratingBlock's method-name policy.
+    ITERATING_METHODS = %i[
+      all? any? chain chunk chunk_while collect collect_concat count cycle
+      detect drop drop_while each each_cons each_entry each_slice
+      each_with_index each_with_object entries filter filter_map find
+      find_all find_index flat_map grep grep_v group_by inject lazy map
+      max max_by min min_by minmax minmax_by none? one? partition reduce
+      reject reverse_each select slice_after slice_before slice_when sort
+      sort_by sum take take_while tally to_h uniq zip with_index with_object
+      bsearch bsearch_index collect! combination d_permutation delete_if
+      each_index keep_if map! permutation product reject! repeat
+      repeated_combination select! sort! each_key each_pair each_value
+      fetch fetch_values has_key? merge merge! transform_keys transform_keys!
+      transform_values transform_values!
+    ].freeze
+
+    # Analyzes method bodies with Prism and the RuboCop 1.92.1 counting rules.
+    #
+    # @param source [String] Ruby source text
+    # @param path [String] source label used in results and parse errors
+    # @return [Array<MethodInfo>] methods in traversal order, including nested definitions
+    # @raise [Error] if source cannot be parsed
+    # @example Analyze a method without loading it
+    #   Analyzer.new.call("def eligible?(age) = age >= 18", path: "person.rb")
     def call(source, path:)
       result = Prism.parse(source)
       unless result.success?
@@ -13,34 +38,104 @@ module Crap4Ruby
 
     private
 
+    # Tracks lexical owners; skips owners that cannot be resolved statically.
+    #
+    # @param node [Prism::Node, nil] subtree to visit
+    # @param scope [Array<String>] lexical namespace components
+    # @param singleton [Boolean] whether definitions belong to a singleton class
+    # @param path [String] source label
+    # @return [Array<MethodInfo>] discovered method definitions
     def discover(node, scope, singleton, path)
       return [] unless node
 
       case node
       when Prism::ClassNode, Prism::ModuleNode
-        owner = qualify(node.constant_path, scope, declaration: true)
-        owner ? discover(node.body, owner, false, path) : []
+        discover_class(node, scope, singleton, path)
       when Prism::SingletonClassNode
         owner = node.expression.is_a?(Prism::SelfNode) ? scope : qualify(node.expression, scope)
         owner ? discover(node.body, owner, true, path) : []
       when Prism::DefNode
         discover_method(node, scope, singleton, path)
+      when Prism::CallNode
+        discover_call(node, scope, singleton, path)
+      else
+        node.compact_child_nodes.flat_map { |child| discover(child, scope, singleton, path) }
+      end
+    end
+
+    def discover_class(node, scope, singleton, path)
+      # @type var methods: Array[MethodInfo]
+      methods = node.is_a?(Prism::ClassNode) ? discover(node.superclass, scope, singleton, path) : []
+      owner = qualify(node.constant_path, scope, declaration: true)
+      methods + (owner ? discover(node.body, owner, false, path) : [])
+    end
+
+    def discover_call(node, scope, singleton, path)
+      name = defined_name(node)
+      block = node.block
+      if name && block.is_a?(Prism::BlockNode)
+        discover_block(block, name, scope, singleton, path)
       else
         node.compact_child_nodes.flat_map { |child| discover(child, scope, singleton, path) }
       end
     end
 
+    def discover_block(block, name, scope, singleton, path)
+      raise EncodingError unless name.valid_encoding?
+
+      name = name.encode(Encoding::UTF_8)
+      parameters = block.parameters
+      header = parameters.is_a?(Prism::BlockParametersNode) ? parameters.location : block.opening_loc
+      lines = body_lines(block.body, after: header.end_line, ending: block.location)
+      name = "self.#{name}" if singleton
+      [MethodInfo.new(name, scope.empty? ? "Object" : scope.join("::"), 1 + decisions(block.body), lines, path)] +
+        discover(block.parameters, scope, singleton, path) + discover(block.body, scope, singleton, path)
+    rescue EncodingError
+      raise Error, "#{path}:#{block.location.start_line}: define_method name must be representable in UTF-8"
+    end
+
+    def defined_name(node)
+      return unless node.is_a?(Prism::CallNode) && node.name == :define_method && node.receiver.nil?
+      return unless node.block.is_a?(Prism::BlockNode)
+
+      arguments = node.arguments&.arguments
+      return unless arguments && arguments.size == 1
+
+      name = arguments.first
+      name.unescaped if name.is_a?(Prism::SymbolNode) || name.is_a?(Prism::StringNode)
+    end
+
+    # Builds this method's entry and discovers nested definitions.
+    #
+    # @param node [Prism::DefNode] method definition
+    # @param scope [Array<String>] lexical namespace components
+    # @param singleton [Boolean] whether the enclosing scope is a singleton class
+    # @param path [String] source label
+    # @return [Array<MethodInfo>] this method and its nested definitions
     def discover_method(node, scope, singleton, path)
-      owner = node.receiver && !node.receiver.is_a?(Prism::SelfNode) ? qualify(node.receiver, scope) : scope
+      owner = method_owner(node, scope)
       return [] unless owner
 
-      name = "#{'self.' if singleton || node.receiver}#{node.name}"
-      lines = body_lines(node.body)
-      complexity = 1 + decisions(node.parameters) + decisions(node.body)
+      name = "#{"self." if singleton || node.receiver}#{node.name}"
+      header = node.equal_loc || node.rparen_loc || node.parameters&.location || node.name_loc
+      lines = body_lines(node.body, after: header.end_line, ending: node.location)
+      complexity = 1 + decisions(node.body)
       [MethodInfo.new(name, owner.empty? ? "Object" : owner.join("::"), complexity, lines, path)] +
+        discover(node.parameters, scope, singleton, path) +
         discover(node.body, scope, singleton, path)
     end
 
+    def method_owner(node, scope)
+      node.receiver && !node.receiver.is_a?(Prism::SelfNode) ? qualify(node.receiver, scope) : scope
+    end
+
+    # Resolves constant syntax without looking up runtime constants.
+    # Declarations append names; references can reuse a lexical ancestor.
+    #
+    # @param node [Prism::Node, nil] namespace expression
+    # @param scope [Array<String>] lexical namespace components
+    # @param declaration [Boolean] whether the expression declares a namespace
+    # @return [Array<String>, nil] qualified components, or nil for dynamic expressions
     def qualify(node, scope, declaration: false)
       case node
       when Prism::ParenthesesNode
@@ -50,41 +145,139 @@ module Crap4Ruby
         ancestor = scope.rindex(name) unless declaration
         ancestor ? scope.take(ancestor + 1) : scope + [name]
       when Prism::ConstantPathNode
-        (node.parent ? qualify(node.parent, scope) : [])&.+([node.name.to_s])
+        # @type var parent: Array[String]?
+        parent = node.parent ? qualify(node.parent, scope) : []
+        parent&.+([node.name.to_s])
       end
     end
 
-    def decisions(node)
+    # Counts the entire body, with RuboCop's per-method safe-navigation discount.
+    #
+    # @param node [Prism::Node, nil] subtree to measure
+    # @return [Integer] number of decisions, excluding the method's base complexity
+    # @param seen [Hash<Symbol, Boolean>] local receivers since their last assignment
+    # @param target [Boolean] whether a target node belongs to an assignment
+    def decisions(node, seen = {}, target: false)
       return 0 unless node
-      return 0 if boundary?(node)
 
-      decision = [:if_node, :unless_node, :while_node, :until_node, :for_node,
-        :when_node, :in_node, :rescue_node, :rescue_modifier_node, :and_node, :or_node].include?(node.type) ||
-        node.type.to_s.match?(/_(?:and|or)_write_node\z/)
-      count = decision ? 1 : 0
-      count += 1 if node.respond_to?(:safe_navigation?) && node.safe_navigation?
-      count + node.compact_child_nodes.sum { |child| decisions(child) }
+      case node
+      when Prism::LocalVariableWriteNode, Prism::LocalVariableAndWriteNode,
+          Prism::LocalVariableOrWriteNode, Prism::LocalVariableOperatorWriteNode
+        seen.delete(node.name)
+      when Prism::LocalVariableTargetNode
+        seen.delete(node.name) if target
+      end
+      count = decision?(node) ? 1 : 0
+      count += 1 if iteration?(node)
+      count += 1 if safe_navigation?(node, seen)
+      count + child_decisions(node, seen, target)
+    end
+
+    def child_decisions(node, seen, target)
+      # RuboCop visits unless branches and guarded patterns in this order.
+      if node.is_a?(Prism::UnlessNode)
+        return decisions(node.predicate, seen) + decisions(node.else_clause, seen) + decisions(node.statements, seen)
+      end
+
+      if node.is_a?(Prism::InNode)
+        guard = node.pattern
+        if guard.is_a?(Prism::IfNode) || guard.is_a?(Prism::UnlessNode)
+          return decisions(guard.statements, seen) + decisions(guard.predicate, seen) + decisions(node.statements, seen)
+        end
+      end
+      node.compact_child_nodes.sum { |child| decisions(child, seen, target: assignment_target?(node, child, target)) }
+    end
+
+    def assignment_target?(node, child, target)
+      case node
+      when Prism::MultiWriteNode then child != node.value
+      when Prism::MultiTargetNode, Prism::SplatNode then target
+      when Prism::ForNode then child == node.index
+      when Prism::RescueNode then child == node.reference
+      else false
+      end
+    end
+
+    def decision?(node)
+      return !node.begin_modifier? if node.is_a?(Prism::WhileNode) || node.is_a?(Prism::UntilNode)
+
+      %i[if_node unless_node for_node
+        when_node in_node rescue_modifier_node and_node or_node].include?(node.type) ||
+        node.type.to_s.match?(/_(?:and|or)_write_node\z/) ||
+        (node.is_a?(Prism::BeginNode) && !node.rescue_clause.nil?)
+    end
+
+    def safe_navigation?(node, seen)
+      case node
+      when Prism::CallNode, Prism::CallAndWriteNode, Prism::CallOrWriteNode,
+          Prism::CallOperatorWriteNode, Prism::CallTargetNode, Prism::IndexAndWriteNode,
+          Prism::IndexOrWriteNode, Prism::IndexOperatorWriteNode, Prism::IndexTargetNode
+        return false unless node.safe_navigation?
+
+        receiver = node.receiver
+        return true unless receiver.is_a?(Prism::LocalVariableReadNode)
+        return false if seen[receiver.name]
+
+        seen[receiver.name] = true
+      else
+        false
+      end
+    end
+
+    def iteration?(node)
+      return false unless node.is_a?(Prism::CallNode) && ITERATING_METHODS.include?(node.name)
+
+      block = node.block
+      return false unless block
+      return true unless block.is_a?(Prism::BlockNode)
+
+      parameters = block.parameters
+      !parameters || parameters.is_a?(Prism::BlockParametersNode)
     end
 
     def boundary?(node)
-      [Prism::DefNode, Prism::ClassNode, Prism::ModuleNode, Prism::SingletonClassNode].any? { |type| node.is_a?(type) }
+      [Prism::DefNode, Prism::ClassNode, Prism::ModuleNode, Prism::SingletonClassNode].any? do |type|
+        node.is_a?(type)
+      end ||
+        !defined_name(node).nil?
     end
 
-    def body_lines(node)
+    # Selects body lines without nested methods, classes, or modules.
+    #
+    # @param node [Prism::Node, nil] method body
+    # @param after [Integer] last line of the method declaration
+    # @param ending [Prism::Location] definition location, including its closing delimiter
+    # @return [Array<Integer>, nil] body lines; nil when shared with the declaration
+    def body_lines(node, after:, ending:)
       return [] unless node
 
-      lines = (node.location.start_line..node.location.end_line).to_a
-      excluded = []
-      collect_boundaries(node, excluded)
-      lines - excluded
+      # @type var start: Prism::Node?
+      start = node.is_a?(Prism::BeginNode) && !node.begin_keyword_loc ? node.compact_child_nodes.first : node
+      return [] unless start
+      return nil if start.location.start_line <= after
+
+      excluded = [] #: Array[Integer]
+      last_line = body_end_line(node, excluded)
+      lines = (start.location.start_line..last_line).to_a - excluded
+      return nil if lines.include?(ending.end_line) && trailing_code?(ending)
+
+      lines
     end
 
-    def collect_boundaries(node, excluded)
-      if boundary?(node)
-        excluded.concat((node.location.start_line..node.location.end_line).to_a)
-      else
-        node.compact_child_nodes.each { |child| collect_boundaries(child, excluded) }
+    def trailing_code?(location)
+      tail = location.slice_lines.lines.last.to_s.byteslice(location.end_column..).to_s
+      !tail.match?(/\A[;\s]*(?:#|\z)/)
+    end
+
+    # Heredoc interpolations can extend beyond their parent node's location.
+    def body_end_line(node, excluded)
+      last_line = node.location.end_line
+      node.compact_child_nodes.each do |child|
+        child_line = body_end_line(child, excluded)
+        last_line = child_line if child_line > last_line
       end
+      excluded.concat((node.location.start_line..last_line).to_a) if boundary?(node)
+      last_line
     end
   end
 end

data/lib/crap4ruby/cli.rb

@@ -3,12 +3,25 @@
 require "optparse"
 
 module Crap4Ruby
+  # Coordinates file discovery, coverage, scoring, and CLI output.
   class CLI
+    # Sets output destinations without running an analysis.
+    #
+    # @param stdout [#puts, #write] destination for reports, help, and version output
+    # @param stderr [#puts, #write] destination for diagnostics and coverage command output
     def initialize(stdout: $stdout, stderr: $stderr)
       @stdout = stdout
       @stderr = stderr
     end
 
+    # Runs the requested analysis and replaces the snapshot after successful scoring.
+    # Help and version requests produce output without writing a snapshot.
+    # Expected usage, input, filesystem, and command errors are printed to stderr.
+    #
+    # @param arguments [Array<String>] command-line tokens; option parsing mutates this array
+    # @return [Integer] 0 on success, 1 on error or an uncertain threshold, 2 on a measured violation
+    # @example Analyze complexity without coverage
+    #   CLI.new.run(["--no-coverage", "--source-root", "lib"])
     def run(arguments)
       options, parser, paths = parse_options(arguments)
       return @stdout.puts(parser) || 0 if options[:help]
@@ -20,10 +33,7 @@ module Crap4Ruby
 
       files = Discovery.call(root: root, source_roots: options[:source_roots], paths: paths, changed: options[:changed])
       coverage = load_coverage(options, root) unless options[:no_coverage] || files.empty?
-      entries = files.flat_map do |path|
-        Analyzer.new.call(File.binread(path), path: path).map { |method| Score.call(method, coverage) }
-      end
-      entries = Report.sorted(entries)
+      entries = Report.sorted(analyze(files, coverage))
       path = Report.write(entries, root: root)
       @stdout.write(Report.table(entries))
       @stderr.puts("Wrote #{path}")
@@ -35,22 +45,52 @@ module Crap4Ruby
 
     private
 
+    def analyze(files, coverage)
+      files.flat_map do |path|
+        Analyzer.new.call(File.binread(path), path: path).map { |method| Score.call(method, coverage) }
+      end
+    end
+
+    # Removes parsed options from arguments and returns the remaining path selectors.
+    #
+    # @param arguments [Array<String>] mutable command-line tokens
+    # @return [Array(Hash, OptionParser, Array<String>)] options, parser, and remaining selectors
+    # @raise [OptionParser::ParseError] if an option or threshold is invalid
     def parse_options(arguments)
+      # @type var options: options
       options = {root: Dir.pwd, source_roots: [], changed: false, coverage: "coverage/.resultset.json"}
       parser = OptionParser.new do |cli|
         cli.banner = "Usage: crap4ruby [options] [file-or-directory-or-filter ...]"
-        cli.on("--root PATH", "Project root (default: current directory)") { |path| options[:root] = path }
-        cli.on("--source-root PATH", "Analyze this directory; repeat for multiple roots") { |path| options[:source_roots] << path }
+        cli.on("--root PATH", "Project root (default: current directory)") do |path|
+          # @type var path: String
+          options[:root] = path
+        end
+        cli.on("--source-root PATH", "Analyze this directory; repeat for multiple roots") do |path|
+          # @type var path: String
+          options[:source_roots] << path
+        end
         cli.on("--changed", "Analyze Git additions and edits, including untracked files") { options[:changed] = true }
-        cli.on("--coverage PATH", "SimpleCov resultset (default: coverage/.resultset.json)") { |path| options[:coverage] = path }
+        cli.on("--coverage PATH", "SimpleCov resultset (default: coverage/.resultset.json)") do |path|
+          # @type var path: String
+          options[:coverage] = path
+        end
         cli.on("--no-coverage", "Complexity only; coverage and CRAP are N/A") { options[:no_coverage] = true }
-        cli.on("--use-existing-coverage", "Read reports without running tests (the default)") { options[:existing] = true }
-        cli.on("--coverage-command COMMAND", "Run a shell command that refreshes the resultset") { |command| options[:command] = command }
-        cli.on("--threshold NUMBER", "Exit 2 when CRAP exceeds this value") do |value|
+        cli.on("--use-existing-coverage", "Read reports without running tests (the default)") do
+          options[:existing] = true
+        end
+        cli.on("--coverage-command COMMAND", "Run a shell command that refreshes the resultset") do |command|
+          # @type var command: String
+          options[:command] = command
+        end
+        cli.on("--threshold NUMBER", "Exit 2 above limit; exit 1 if unknown scores could exceed it") do |value|
+          # @type var value: String
           number = Float(value)
-          raise OptionParser::InvalidArgument, "threshold must be finite and nonnegative" unless number.finite? && number >= 0
+          raise ArgumentError unless number.finite?
+
+          threshold = Rational(value, exception: false) || number.to_r
+          raise ArgumentError if threshold.negative?
 
-          options[:threshold] = number
+          options[:threshold] = threshold
         rescue ArgumentError
           raise OptionParser::InvalidArgument, "threshold must be finite and nonnegative"
         end
@@ -60,19 +100,36 @@ module Crap4Ruby
       [options, parser, parser.parse(arguments)]
     end
 
+    # Rejects a coverage command when coverage is disabled or explicitly read-only.
+    #
+    # @param options [Hash] parsed CLI options
+    # @return [void]
+    # @raise [Error] if coverage options conflict
     def validate_options(options)
-      if options[:command] && (options[:no_coverage] || options[:existing])
-        raise Error, "--coverage-command cannot be combined with --no-coverage or --use-existing-coverage"
-      end
+      return unless options[:command] && (options[:no_coverage] || options[:existing])
+
+      raise Error, "--coverage-command cannot be combined with --no-coverage or --use-existing-coverage"
     end
 
+    # Checks measured scores and bounds unknown scores at zero coverage.
+    #
+    # @param entries [Array<Entry>] scored methods
+    # @param threshold [Rational, nil] maximum allowed score, or nil to disable the check
+    # @return [Integer] 2 for a measured violation, 1 if uncertain, otherwise 0
     def threshold_status(entries, threshold)
-      if threshold && entries.any? { |entry| entry.crap && entry.crap > threshold }
-        @stderr.puts("CRAP threshold exceeded: #{threshold}")
-        2
-      else
-        0
+      return 0 unless threshold
+
+      if entries.any? { |entry| entry.crap && entry.crap > threshold }
+        @stderr.puts("CRAP threshold exceeded")
+        return 2
+      end
+
+      uncertain = entries.select { |entry| !entry.crap && entry.complexity * (entry.complexity + 1) > threshold }
+      uncertain.each do |entry|
+        @stderr.puts("Cannot verify CRAP threshold: #{Report.label("#{entry.namespace}##{entry.name}")} " \
+                     "has unknown coverage (maximum #{entry.complexity * (entry.complexity + 1)})")
       end
+      uncertain.empty? ? 0 : 1
     end
 
     def load_coverage(options, root)
@@ -81,6 +138,15 @@ module Crap4Ruby
       Coverage.load(report, root: root)
     end
 
+    # Runs a shell command at root and forwards its combined output to stderr.
+    # Requires success and a changed report stamp before coverage can be consumed.
+    #
+    # @param command [String] command passed to `sh -c` with the caller's environment
+    # @param root [String] command working directory
+    # @param report [String] expected coverage report path
+    # @return [void]
+    # @raise [Error] if the command is empty, fails, or leaves the report stamp unchanged
+    # @raise [SystemCallError] if the command cannot start or report metadata cannot be read
     def run_coverage(command, root, report)
       raise Error, "--coverage-command must not be empty" if command.strip.empty?
 
@@ -90,10 +156,18 @@ module Crap4Ruby
         output.each_line { |line| @stderr.write(line) }
         process.value
       end
-      raise Error, "coverage command failed (exit #{status.exitstatus || "signal #{status.termsig}"})" unless status.success?
+      unless status.success?
+        raise Error,
+          "coverage command failed (exit #{status.exitstatus || "signal #{status.termsig}"})"
+      end
       raise Error, "coverage command did not refresh #{report}" if report_stamp(report) == before
     end
 
+    # Captures metadata used to detect a newly generated or refreshed report.
+    #
+    # @param path [String] coverage report path
+    # @return [Array(Integer, Time, Time, Integer), nil] inode, modification time,
+    #   change time, and size; nil if the path does not exist
     def report_stamp(path)
       stat = File.stat(path)
       [stat.ino, stat.mtime, stat.ctime, stat.size]

data/lib/crap4ruby/coverage.rb

@@ -3,15 +3,28 @@
 require "json"
 
 module Crap4Ruby
+  # Merges SimpleCov line coverage across named test suites.
   class Coverage
+    # Reads a SimpleCov resultset, accepting legacy arrays and line-coverage objects.
+    #
+    # @param path [String] JSON resultset path, relative to the working directory or absolute
+    # @param root [String] base directory for source paths inside the report
+    # @return [Coverage] merged coverage
+    # @raise [Error] if the report cannot be read, parsed, or validated
     def self.load(path, root:)
       new(JSON.parse(File.read(path)), root: root)
     rescue SystemCallError => error
-      raise Error, "#{path}: cannot read coverage report; generate SimpleCov coverage or use --no-coverage (#{error.message})"
+      raise Error,
+        "#{path}: cannot read coverage report; generate SimpleCov coverage or use --no-coverage (#{error.message})"
     rescue JSON::ParserError, Error => error
       raise Error, "#{path}: invalid SimpleCov report (#{error.message})"
     end
 
+    # Validates and merges suite reports by the maximum hit count for each line.
+    #
+    # @param suites [Hash{String => Hash}] parsed resultset keyed by suite name
+    # @param root [String] base directory for relative source paths
+    # @raise [Error] if suites or line coverage are malformed
     def initialize(suites, root:)
       raise Error, "expected named test suites" unless suites.is_a?(Hash) && !suites.empty?
 
@@ -19,27 +32,43 @@ module Crap4Ruby
       suites.each_value { |suite| add_suite(suite, root) }
     end
 
+    # Measures executable body lines with positive hit counts.
+    # Null and out-of-range lines do not enter the denominator.
+    #
+    # @param method [MethodInfo] method whose path and body lines select coverage
+    # @return [Rational, nil] exact fraction from 0 to 1; zero for an absent file,
+    #   or nil when body lines are ambiguous or no reported lines are measurable
     def fraction(method)
+      body = method.lines
+      return nil unless body
+
       path = File.expand_path(method.path)
       path = File.realpath(path) if File.exist?(path)
+      # @type var lines: Array[Integer?]?
       lines = @files[path]
-      return 0.0 unless lines
+      return Rational(0) unless lines
 
-      hits = method.lines.filter_map { |line| lines[line - 1] }
+      hits = body.filter_map { |line| lines[line - 1] }
       return nil if hits.empty?
 
-      hits.count(&:positive?).fdiv(hits.size)
+      Rational(hits.count(&:positive?), hits.size)
     end
 
     private
 
     def add_suite(suite, root)
-      unless suite.is_a?(Hash) && suite["coverage"].is_a?(Hash)
-        raise Error, "expected a coverage object for each suite"
-      end
+      raise Error, "expected a coverage object for each suite" unless suite.is_a?(Hash) && suite["coverage"].is_a?(Hash)
+
       suite["coverage"].each { |path, data| add_file(path, data, root) }
     end
 
+    # Normalizes a source path and merges line counts across suites.
+    #
+    # @param path [String] source path from a suite report
+    # @param data [Array<Integer, nil>, Hash] legacy counts or an object with a `lines` array
+    # @param root [String] base directory for relative source paths
+    # @return [void]
+    # @raise [Error] if line counts are invalid
     def add_file(path, data, root)
       key = File.expand_path(path, root)
       key = File.realpath(key) if File.exist?(key)
@@ -47,6 +76,9 @@ module Crap4Ruby
       unless lines.is_a?(Array) && lines.all? { |hit| hit.nil? || (hit.is_a?(Integer) && hit >= 0) }
         raise Error, "#{path}: expected nonnegative line counts or null"
       end
+
+      # Every element was validated above; Steep cannot narrow an array through all?.
+      lines = lines #: Array[Integer?]
       previous = @files[key] || []
       @files[key] = Array.new([previous.size, lines.size].max) do |index|
         [previous[index], lines[index]].compact.max

data/lib/crap4ruby/discovery.rb

@@ -4,11 +4,45 @@ require "find"
 require "open3"
 
 module Crap4Ruby
+  # Selects Ruby source files from explicit paths, directories, and Git changes.
   module Discovery
+    # Directory names excluded during recursive traversal.
     EXCLUDED = %w[test tests spec features vendor node_modules target coverage tmp log pkg build dist].freeze
 
+    # Combines source roots and existing paths, then applies filters and Git selection.
+    # Explicit files bypass traversal exclusions but must have the `.rb` extension.
+    # Defaults to the project root when no source roots or existing paths are given.
+    #
+    # @param root [String] absolute project directory
+    # @param source_roots [Array<String>] source directories, absolute or relative to root
+    # @param paths [Array<String>] existing paths or substring filters relative to root
+    # @param changed [Boolean] restrict results to staged, unstaged, and untracked files
+    # @return [Array<String>] sorted, unique real paths; substring filters use OR
+    # @raise [Error] if a source root is not a directory or Git fails
+    # @raise [SystemCallError] if paths cannot be read or resolved
     def self.call(root:, source_roots:, paths:, changed:)
       existing, filters = paths.partition { |path| File.exist?(File.expand_path(path, root)) }
+      roots = selection_roots(root, source_roots, existing)
+      files = roots.flat_map { |path| File.file?(path) ? [path] : walk(path) }
+      files = files.select { |path| File.extname(path) == ".rb" }.map { |path| File.realpath(path) }.uniq.sort
+      unless filters.empty?
+        files.select! do |path|
+          filters.any? do |filter|
+            path.delete_prefix("#{root}/").include?(filter)
+          end
+        end
+      end
+      files &= changed_files(root) if changed
+      files
+    end
+
+    # Validates directory roots and combines them with explicit paths.
+    #
+    # @param root [String] absolute project directory
+    # @param source_roots [Array<String>] explicit source directories
+    # @param existing [Array<String>] existing positional paths
+    # @return [Array<String>] expanded roots, defaulting to the project directory
+    def self.selection_roots(root, source_roots, existing)
       roots = source_roots.map do |path|
         directory = File.expand_path(path, root)
         raise Error, "#{path}: source root must be a directory" unless File.directory?(directory)
@@ -17,15 +51,17 @@ module Crap4Ruby
       end
       roots.concat(existing.map { |path| File.expand_path(path, root) })
       roots << root if roots.empty?
-      files = roots.flat_map { |path| File.file?(path) ? [path] : walk(path) }
-      files = files.select { |path| File.extname(path) == ".rb" }.map { |path| File.realpath(path) }.uniq.sort
-      files.select! { |path| filters.any? { |filter| path.delete_prefix("#{root}/").include?(filter) } } unless filters.empty?
-      files &= changed_files(root) if changed
-      files
+      roots
     end
 
+    # Walks a directory without following symlinks or entering excluded directories.
+    # Hidden files and test/spec filenames are excluded; extensions are not filtered.
+    #
+    # @param root [String] directory to traverse, including an explicitly selected hidden directory
+    # @return [Array<String>] candidate file paths in traversal order
+    # @raise [SystemCallError] if traversal fails
     def self.walk(root)
-      paths = []
+      paths = [] #: Array[String]
       Find.find(root) do |path|
         name = File.basename(path)
         if File.directory?(path)
@@ -37,6 +73,13 @@ module Crap4Ruby
       paths
     end
 
+    # Runs Git in the project directory without a shell.
+    #
+    # @param root [String] working directory for Git
+    # @param arguments [Array<String>] command and arguments
+    # @return [String] standard output, preserving NUL separators
+    # @raise [Error] if Git exits unsuccessfully
+    # @raise [SystemCallError] if Git cannot be started
     def self.git(root, *arguments)
       output, error, status = Open3.capture3("git", "-C", root, *arguments)
       raise Error, "git: #{error.strip}" unless status.success?
@@ -44,11 +87,18 @@ module Crap4Ruby
       output
     end
 
+    # Finds existing staged, unstaged, and untracked files under the project directory.
+    # Deleted files are omitted and renames are treated as deletion and addition.
+    #
+    # @param root [String] directory inside a Git working tree
+    # @return [Array<String>] real paths, without extension or traversal filtering
+    # @raise [Error] if Git cannot inspect the working tree
+    # @raise [SystemCallError] if Git cannot start or a path cannot be resolved
     def self.changed_files(root)
       top = git(root, "rev-parse", "--show-toplevel").chomp
       git(root, "status", "--porcelain=v1", "-z", "--no-renames", "--untracked-files=all", "--", ".")
         .split("\0").filter_map do |entry|
-          path = File.join(top, entry[3..])
+          path = File.join(top, entry[3..].to_s)
           File.realpath(path) if File.file?(path)
         end
     end