hashira 0.4.0 → 0.5.1

data/lib/hashira/duplication/similarity.rb

@@ -38,6 +38,10 @@ class Hashira::Duplication::Similarity
   end
 
   def cell(prev, row, token, index)
-    @right[index] == token ? prev[index] + 1 : [prev[index + 1], row[index]].max
+    match?(token, index) ? prev[index] + 1 : carry(prev, row, index)
   end
+
+  def match?(token, index) = @right[index] == token
+
+  def carry(prev, row, index) = [prev[index + 1], row[index]].max
 end

data/lib/hashira/duplication/variance.rb

@@ -40,10 +40,10 @@ class Hashira::Duplication::Variance
   end
 
   def signature(node)
-    type = node.type
-    return literal(node) if LITERALS.include?(type)
-    node.name if NAMED.include?(type)
+    LITERALS.include?(node.type) ? literal(node) : label(node)
   end
 
+  def label(node) = (node.name if NAMED.include?(node.type))
+
   def literal(node) = VALUED.include?(node.type) ? node.value : node.unescaped
 end

data/lib/hashira/hotspots/rollup.rb

@@ -19,7 +19,7 @@ class Hashira::Hotspots::Rollup
     )
   end
 
-  def scores = @complexity ? @complexity.methods : []
+  def scores = @complexity ? @complexity.ranked : []
 
   def clusters = @duplication ? @duplication.clusters : []
 

data/lib/hashira/pipeline.rb

@@ -1,27 +1,37 @@
 # frozen_string_literal: true
 
 require "prism"
+require_relative "coupling/report"
+require_relative "smells/report"
 
 class Hashira::Pipeline
-  ANALYZERS = %i[coupling complexity duplication].freeze
+  ANALYZERS = %i[coupling complexity duplication smells].freeze
 
-  RULES = [Hashira::Analysis::CycleFindings, Hashira::Analysis::SdpViolationFindings].freeze
+  STRUCTURAL = Hashira::Coupling::Report::RULES.map { it::KIND }.freeze
+
+  SMELLS = Hashira::Smells::Report::CHECKS.map(&:kind).sort.freeze
 
   def initialize(project, enabled: ANALYZERS, packaging: :auto)
     @project = project
     @enabled = enabled
     @trees = project.files.to_h { [it, parse(it)] }
-    @graph = Hashira::Analysis::Graph.new(project, @trees, census(settle(packaging)))
+    @coupling = Hashira::Coupling::Report.new(project, @trees, packaging: settle(packaging))
   end
 
-  attr_reader :project, :graph
+  attr_reader :project
+
+  def graph = @coupling.graph
 
   def complexity
-    @complexity ||= Hashira::Complexity::Analyzer.new(@project, @trees) if enabled?(:complexity)
+    @complexity ||= Hashira::Complexity::Scores.new(@project, @trees) if enabled?(:complexity)
   end
 
   def duplication
-    @duplication ||= Hashira::Duplication::Analyzer.new(@project, @trees, churn) if enabled?(:duplication)
+    @duplication ||= Hashira::Duplication::Clones.new(@project, @trees, churn) if enabled?(:duplication)
+  end
+
+  def smells
+    @smells ||= Hashira::Smells::Report.new(@project, @trees) if enabled?(:smells)
   end
 
   def hotspots
@@ -32,18 +42,16 @@ class Hashira::Pipeline
 
   def enabled?(analyzer) = @enabled.include?(analyzer)
 
-  def findings = structural + listed(complexity) + listed(duplication)
+  def findings = structural + listed(complexity) + listed(duplication) + listed(smells)
 
   private
 
-  def census(packaging) = Hashira::Analysis::Census.new(@project, @trees, packaging:)
-
   def settle(packaging)
     return packaging unless packaging == :auto
     @project.rails? ? :namespace : :folder
   end
 
-  def structural = enabled?(:coupling) ? RULES.flat_map { it.new(@project, @graph).list } : []
+  def structural = enabled?(:coupling) ? @coupling.findings : []
 
   def listed(analyzer) = analyzer ? analyzer.findings : []
 

data/lib/hashira/report/complexity_table.rb

@@ -13,7 +13,7 @@ class Hashira::Report::ComplexityTable
   end
 
   def print
-    section(@complexity.methods, METHOD_ROW, %w[method Cog Calls Loc], METHOD_TITLE)
+    section(@complexity.ranked, METHOD_ROW, %w[method Cog Calls Loc], METHOD_TITLE)
     section(@complexity.classes, CLASS_ROW, %w[class Cog Methods Peak], CLASS_TITLE)
   end
 

data/lib/hashira/report/finding_lines.rb

@@ -10,7 +10,7 @@ class Hashira::Report::FindingLines
   end
 
   def print
-    @io.puts("#{@indent}#{@finding.kind}: #{@finding.message}")
+    @io.puts("#{@indent}#{@finding.kind}: #{Hashira::Report::Phrases.message(@finding)}")
     @finding.evidence.first(SAMPLE).each { @io.puts("#{@indent}    · #{it}") }
   end
 

data/lib/hashira/report/json.rb

@@ -17,7 +17,9 @@ class Hashira::Report::Json
 
   def payload = base.merge(coupling).merge(sections.compact)
 
-  def base = { findings: @view.findings.all.map(&:to_h), accepted: accepted }
+  def base = { findings: @view.findings.all.map { rendered(it) }, accepted: accepted }
+
+  def rendered(finding) = finding.to_h.merge(message: Hashira::Report::Phrases.message(finding))
 
   def coupling
     graph = @view.graph
@@ -33,12 +35,12 @@ class Hashira::Report::Json
   end
 
   def accepted
-    @view.findings.accepted.map { |finding, reason| finding.to_h.merge(reason:) }
+    @view.findings.accepted.map { |finding, reason| rendered(finding).merge(reason:) }
   end
 
   def complexity = { methods: the_methods, classes: the_classes }
 
-  def the_methods = @view.complexity.methods.map(&:to_h)
+  def the_methods = @view.complexity.ranked.map(&:to_h)
 
   def the_classes = @view.complexity.classes.map(&:to_h)
 

data/lib/hashira/report/phrases.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Hashira::Report::Phrases
+  COMPLEXITY_ADVICE = {
+    "if" => "flatten the branching — guard clauses, early returns, or polymorphism.",
+    "elsif" => "replace the elsif ladder with a lookup or polymorphic dispatch.",
+    "else" => "flatten the branching — guard clauses, early returns, or polymorphism.",
+    "case" => "a case this size often wants polymorphism or a dispatch table.",
+    "boolean" => "name the compound condition in a predicate method.",
+    "rescue" => "narrow the rescue, or lift error handling to the caller.",
+    "while" => "extract the loop body into its own method.",
+    "until" => "extract the loop body into its own method.",
+    "for" => "extract the loop body into its own method.",
+    "unless" => "invert to a guard clause or a named predicate.",
+    "ternary" => "extract the nested ternary into a named method."
+  }.freeze
+
+  DUPLICATION_ADVICE = {
+    identical: "byte-for-byte identical — extract a shared method and call it from each site.",
+    literal: "differs only in literal values — extract a method, pass them as arguments.",
+    message: "differs only in the receiver or message — extract a method taking the receiver.",
+    constant: "differs only in a constant — extract a method and parameterize it.",
+    structure: "the control flow differs — extract the common core, but verify by hand (lower confidence).",
+    mixed: "extract the shared shape and pass what differs as parameters."
+  }.freeze
+
+  module_function
+
+  def message(finding) = public_send("on_#{finding.kind}", finding)
+
+  def on_cycle(finding)
+    detail = finding.detail
+    from, to = detail[:weak]
+    weight = detail[:weight]
+    "#{finding.package} can reach itself: #{finding.cycle.join(" -> ")} — any change may ripple back " \
+      "around. The lightest edge on this cycle is #{from} -> #{to} (#{weight} ref#{"s" unless weight == 1})."
+  end
+
+  def on_sdp_violation(finding)
+    detail = finding.detail
+    from, to = detail.values_at(:from, :to)
+    "#{from} (I=#{score(detail[:from_instability])}) depends on the LESS stable #{to} " \
+      "(I=#{score(detail[:to_instability])}) — churn in #{to} will force churn in #{from}. " \
+      "Invert the edge or extract the stable part of #{to} that #{from} needs."
+  end
+
+  def on_mixed_audience(finding)
+    package = finding.package
+    parts = finding.detail[:parts]
+    "#{package} splits #{parts.size} ways: #{parts.map { clause(it) }.join("; ")} — " \
+      "parts with separate client bases are separate packages in disguise. " \
+      "Split #{package} along that seam#{addendum(parts)}."
+  end
+
+  def on_wide_edge(finding)
+    detail = finding.detail
+    from, to = detail.values_at(:from, :to)
+    names = detail[:constants]
+    "#{from} -> #{to} is #{names.size} constants wide (#{names.join(", ")}) — " \
+      "every one is a reason for #{from} to change. Front #{to} with one facade."
+  end
+
+  def on_roll_call(finding)
+    detail = finding.detail
+    "the words #{detail[:words].join(", ")} are listed together in #{detail[:files].join(", ")} — " \
+      "#{detail[:packages].size} packages keep one roll-call in sync by hand. " \
+      "Make the list data with a single owner."
+  end
+
+  def on_complexity(finding)
+    detail = finding.detail
+    "#{finding.package} — cognitive #{detail[:cognitive]}, #{detail[:calls]} calls " \
+      "(#{detail[:site]}). #{COMPLEXITY_ADVICE.fetch(detail[:dominant])}"
+  end
+
+  def on_duplication(finding)
+    detail = finding.detail
+    "#{detail[:size]} similar fragments (mass #{detail[:mass]}) — " \
+      "#{DUPLICATION_ADVICE.fetch(detail[:kind])}#{footnote(detail)}"
+  end
+
+  def score(value) = format("%.2f", value)
+
+  def clause(part) = "#{part[:users].join(", ")} #{verb(part)} #{part[:constants].join(", ")}"
+
+  def verb(part)
+    return "share" if part[:shared]
+    part[:users].size == 1 ? "alone uses" : "use"
+  end
+
+  def addendum(parts)
+    parts.any? { it[:shared] } ? ", keeping the shared constants as the base layer the rest builds on" : ""
+  end
+
+  def footnote(detail)
+    detail[:hot] ? " Both sites change often — fix one, miss the other." : ""
+  end
+end

data/lib/hashira/report/smell_phrases.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Hashira::Report::Phrases
+  module_function
+
+  def on_control_parameter(finding)
+    detail = finding.detail
+    "#{finding.package} is steered by #{quoted(detail[:names])} (#{detail[:site]}). " \
+      "Split the method, or pass a strategy instead of a flag."
+  end
+
+  def on_data_clump(finding)
+    "#{finding.package} passes the same parameters between methods (#{finding.detail[:site]}). " \
+      "Introduce a parameter object."
+  end
+
+  def on_duplicate_method_call(finding)
+    "#{finding.package} repeats identical calls (#{finding.detail[:site]}). " \
+      "Name the result in a local variable."
+  end
+
+  def on_feature_envy(finding)
+    detail = finding.detail
+    names = detail[:names]
+    "#{finding.package} refers to #{quoted(names)} more than to self (#{detail[:site]}). " \
+      "The behavior may belong on #{names.first}."
+  end
+
+  def on_instance_variable_assumption(finding)
+    "#{finding.package} reads instance variables never set in initialize (#{finding.detail[:site]}). " \
+      "Assign them in initialize, or pass the data explicitly."
+  end
+
+  def on_manual_dispatch(finding)
+    "#{finding.package} dispatches manually via respond_to? (#{finding.detail[:site]}). " \
+      "Trust the duck type, or split the callers into two adapters."
+  end
+
+  def on_module_initialize(finding)
+    "#{finding.package} defines initialize in a module (#{finding.detail[:site]}). " \
+      "Move construction into the including class."
+  end
+
+  def on_nil_check(finding)
+    "#{finding.package} checks for nil (#{finding.detail[:site]}). " \
+      "Prefer a default, a null object, or polymorphism."
+  end
+
+  def on_repeated_conditional(finding)
+    tally(finding, "branches on the same test %d times", "Replace the scattered checks with polymorphism.")
+  end
+
+  def on_too_many_instance_variables(finding)
+    tally(finding, "holds %d instance variables", "Split the class, or gather related fields into value objects.")
+  end
+
+  def on_utility_function(finding)
+    "#{finding.package} touches no instance state (#{finding.detail[:site]}). " \
+      "Move it onto the object it serves, or make it a module function."
+  end
+
+  def tally(finding, event, advice)
+    detail = finding.detail
+    "#{finding.package} #{format(event, detail[:count])} (#{detail[:site]}). #{advice}"
+  end
+
+  def quoted(names) = names.map { "'#{it}'" }.join(", ")
+end

data/lib/hashira/smells/census.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "prism"
+
+class Hashira::Smells::Census
+  def initialize(project, trees)
+    @project = project
+    @trees = trees
+  end
+
+  def types = @trees.flat_map { |path, tree| harvest(@project.relative(path), tree) }
+
+  private
+
+  def harvest(file, tree)
+    found = []
+    Hashira::Analysis::TypeWalk.each(tree) { |node, full| found << context(file, node, full.join("::")) }
+    found
+  end
+
+  def context(file, node, name)
+    Hashira::Smells::TypeContext.new(name:, node:, kind: kind(node), file:, defs: defs(name, node, file))
+  end
+
+  def kind(node) = node.is_a?(Prism::ModuleNode) ? :module : :class
+
+  def defs(name, node, file)
+    Hashira::Smells::Visibility.new(node).entries.map do |def_node, section|
+      Hashira::Smells::MethodContext.new(owner: name, node: def_node, file:, section:)
+    end
+  end
+end

data/lib/hashira/smells/check.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+class Hashira::Smells::Check
+  def self.kind = name.split("::").last.gsub(/(?<=[a-z])(?=[A-Z])/, "_").downcase
+
+  def self.judge? = false
+
+  def initialize(subject)
+    @subject = subject
+  end
+
+  def finding
+    return unless smelly?
+    Hashira::Analysis::Finding.new(kind:, package: label, detail:, evidence:)
+  end
+
+  private
+
+  attr_reader :subject
+
+  def kind = self.class.kind
+
+  def label = subject.subject
+
+  def site = subject.site
+
+  def detail = { site: }
+
+  def spots(nodes) = "#{subject.file}:#{nodes.map { it.location.start_line }.uniq.join(", ")}"
+
+  def evidence = []
+
+  def tally(name, lines) = "#{name} (line#{"s" if lines.size > 1} #{lines.join(", ")})"
+end

data/lib/hashira/smells/conditions.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Hashira::Smells::Conditions
+  TESTED = [Prism::IfNode, Prism::UnlessNode, Prism::CaseNode, Prism::AndNode, Prism::OrNode].freeze
+
+  module_function
+
+  def tested?(node) = TESTED.include?(node.class)
+
+  def fence?(node) = Hashira::Smells::Scope::FENCES.include?(node.class)
+
+  def couple?(node) = node.is_a?(Prism::AndNode) || node.is_a?(Prism::OrNode)
+
+  def condition(node)
+    case node
+    when Prism::IfNode, Prism::UnlessNode, Prism::CaseNode then node.predicate
+    when Prism::AndNode, Prism::OrNode then node.left
+    end
+  end
+
+  def branches(node)
+    return fork(node) if node.is_a?(Prism::IfNode) || node.is_a?(Prism::UnlessNode)
+    return node.conditions + [node.consequent] if node.is_a?(Prism::CaseNode)
+    couple?(node) ? [node.right] : [node.body]
+  end
+
+  def fork(node)
+    [node.statements, node.is_a?(Prism::IfNode) ? node.subsequent : node.else_clause]
+  end
+
+  def nested(roots) = roots.compact.flat_map { seek(it) }
+
+  def seek(node)
+    return [node] if tested?(node)
+    fence?(node) ? [] : node.compact_child_nodes.flat_map { seek(it) }
+  end
+
+  def plain(node)
+    return [] if tested?(node) || fence?(node)
+    [node] + node.compact_child_nodes.flat_map { plain(it) }
+  end
+end

data/lib/hashira/smells/contexts.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Hashira
+  module Smells
+    module Parameters
+      NAMELESS = [Prism::ForwardingParameterNode, Prism::ImplicitRestNode, Prism::NoKeywordsParameterNode].freeze
+
+      module_function
+
+      def names(def_node) = parts(def_node).flat_map { expand(it) }
+
+      def arguments(def_node) = parts(def_node).grep_v(Prism::BlockParameterNode).flat_map { expand(it) }
+
+      def parts(def_node)
+        node = def_node.parameters
+        return [] unless node
+        node.requireds + node.optionals + node.posts + node.keywords +
+          [node.rest, node.keyword_rest, node.block].compact
+      end
+
+      def expand(part)
+        case part
+        when Prism::MultiTargetNode then pieces(part).flat_map { expand(it) }
+        when *NAMELESS then []
+        else [part.name].compact
+        end
+      end
+
+      def pieces(part) = part.lefts + Array(part.rest&.expression) + part.rights
+    end
+
+    MethodContext =
+      Data.define(:owner, :node, :file, :section) do
+        def subject = "#{owner}#{singleton? ? "." : "#"}#{node.name}"
+
+        def line = node.location.start_line
+
+        def singleton? = node.receiver.is_a?(Prism::Node) || section == :singleton
+
+        def mixin? = section == :module_function
+
+        def public? = section == :public && !singleton?
+
+        def parameters = Parameters.names(node)
+
+        def arguments = Parameters.arguments(node)
+
+        def site = "#{file}:#{line}"
+      end
+
+    TypeContext =
+      Data.define(:name, :node, :kind, :file, :defs) do
+        def line = node.location.start_line
+
+        def subject = name
+
+        def owned = defs.reject(&:singleton?)
+
+        def site = "#{file}:#{line}"
+      end
+  end
+end

data/lib/hashira/smells/control_parameter.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+class Hashira::Smells::ControlParameter < Hashira::Smells::Check
+  private
+
+  def smelly? = culprits.any?
+
+  def culprits = @culprits ||= subject.parameters.filter_map { |name| culprit(name) }
+
+  def culprit(name)
+    lines = spots(name).uniq
+    [name, lines] unless lines.empty?
+  end
+
+  def spots(name)
+    Hashira::Smells::ParamCheck.new(subject.node, name).matches.map { it.location.start_line }
+  end
+
+  def detail = { site:, names: culprits.map { |name, _lines| name } }
+
+  def evidence = culprits.map { |name, lines| tally(name, lines) }
+end

data/lib/hashira/smells/data_clump.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+class Hashira::Smells::DataClump < Hashira::Smells::Check
+  MAX_COPIES = 2
+
+  MIN_SIZE = 2
+
+  def self.judge? = true
+
+  private
+
+  def smelly? = clumps.any?
+
+  def candidates = @candidates ||= subject.owned.map { [it, it.arguments.sort] }
+
+  def clumps = @clumps ||= shared.map { |clump| [clump, holders(clump)] }
+
+  def shared = candidates.combination(MAX_COPIES + 1).filter_map { |group| clump(group) }.uniq
+
+  def clump(group)
+    names = group.map(&:last).inject(:&)
+    names if names.size >= MIN_SIZE
+  end
+
+  def holders(clump) = candidates.filter_map { |method, names| method if (clump - names).empty? }
+
+  def evidence = clumps.map { |clump, holders| row(clump, holders) }
+
+  def row(clump, holders)
+    "(#{clump.join(", ")}) → #{holders.size} methods: #{holders.map { |holder| holder.node.name }.join(", ")}"
+  end
+end

data/lib/hashira/smells/duplicate_method_call.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "prism"
+
+class Hashira::Smells::DuplicateMethodCall < Hashira::Smells::Check
+  LIMIT = 1
+
+  private
+
+  def smelly? = repeats.any?
+
+  def calls = @calls ||= Hashira::Smells::Scope.inside(subject.node).grep(Prism::CallNode)
+
+  def plain?(node)
+    !node.receiver && !node.arguments && !node.block.is_a?(Prism::BlockArgumentNode)
+  end
+
+  def repeats
+    @repeats ||= usual.reject { |_handle, nodes| whole.value?(nodes) }.merge(whole)
+  end
+
+  def usual
+    calls.reject { plain?(it) || it.name == :new }
+      .group_by { handle(it) }.select { |_handle, group| group.size > LIMIT }
+  end
+
+  def whole
+    @whole ||=
+      calls.select { it.block.is_a?(Prism::BlockNode) }
+        .group_by { it.slice.gsub(/\s+/, " ") }.select { |_handle, group| group.size > LIMIT }
+  end
+
+  def handle(node) = "#{title(node)}#{signature(node)}"
+
+  def title(node)
+    [node.receiver&.slice, node.name].compact.join(node.safe_navigation? ? "&." : ".")
+  end
+
+  def signature(node)
+    wrap(([node.arguments&.slice] + pass(node.block)).compact)
+  end
+
+  def pass(block) = block.is_a?(Prism::BlockArgumentNode) ? [block.slice] : []
+
+  def wrap(parts) = parts.empty? ? "" : "(#{parts.join(", ")})"
+
+  def evidence
+    repeats.map { |handle, nodes| "#{handle} × #{nodes.size} (#{stamp(lines(nodes))})" }
+  end
+
+  def lines(nodes) = nodes.map { it.location.start_line }.uniq
+
+  def stamp(lines) = "line#{"s" if lines.size > 1} #{lines.join(", ")}"
+end

data/lib/hashira/smells/feature_envy.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+class Hashira::Smells::FeatureEnvy < Hashira::Smells::Check
+  private
+
+  def smelly?
+    !subject.singleton? && !subject.mixin? && refs.ego.positive? && envied.any?
+  end
+
+  def refs = @refs ||= Hashira::Smells::Refs.new(subject.node)
+
+  def envied = @envied ||= refs.envious
+
+  def detail = { site:, names: envied }
+
+  def evidence = envied.map { |name| tally(name, refs.lines(name).uniq) }
+end

data/lib/hashira/smells/instance_variable_assumption.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "prism"
+
+class Hashira::Smells::InstanceVariableAssumption < Hashira::Smells::Check
+  SETTERS = [
+    Prism::InstanceVariableWriteNode, Prism::InstanceVariableOrWriteNode,
+    Prism::InstanceVariableAndWriteNode, Prism::InstanceVariableOperatorWriteNode,
+    Prism::InstanceVariableTargetNode
+  ].freeze
+
+  MAYBES = [
+    Prism::LocalVariableOrWriteNode, Prism::InstanceVariableOrWriteNode,
+    Prism::ClassVariableOrWriteNode, Prism::GlobalVariableOrWriteNode,
+    Prism::ConstantOrWriteNode, Prism::ConstantPathOrWriteNode,
+    Prism::CallOrWriteNode, Prism::IndexOrWriteNode
+  ].freeze
+
+  module Harvest
+    module_function
+
+    def reads(node)
+      return [] if MAYBES.include?(node.class)
+      below = node.compact_child_nodes.flat_map { reads(it) }
+      node.is_a?(Prism::InstanceVariableReadNode) ? below + [node.name] : below
+    end
+  end
+
+  def self.judge? = true
+
+  private
+
+  def smelly? = subject.kind == :class && assumed.any?
+
+  def assumed = @assumed ||= (read - prepared).uniq.sort
+
+  def read = subject.owned.flat_map { Harvest.reads(it.node) }
+
+  def prepared
+    starters.flat_map { Hashira::Smells::Scope.inside(it.node) }.select { SETTERS.include?(it.class) }.map(&:name)
+  end
+
+  def starters = subject.owned.select { it.node.name == :initialize }
+
+  def evidence = assumed.map(&:to_s)
+end