hashira 0.4.0 → 0.5.0

data/lib/hashira/coupling/roll_call_findings.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative "rule"
+
+class Hashira::Coupling::RollCallFindings < Hashira::Coupling::Rule
+  KIND = "roll_call"
+
+  def list = rolls.map { entry(it) }
+
+  private
+
+  def rolls = Hashira::Coupling::RollCall.new(lists, homes).rolls
+
+  def sightings
+    @sightings ||=
+      graph.trees.filter_map do |file, tree|
+        words = Hashira::Coupling::Words.list(tree)
+        [project.relative(file), graph.charge(file), words] unless words.empty?
+      end
+  end
+
+  def lists = sightings.to_h { |file, _home, words| [file, words] }
+
+  def homes = sightings.to_h { |file, home, _words| [file, home] }
+
+  def entry(roll)
+    words, files, packages = roll.deconstruct
+    finding(package: packages.first, digest: words.join(","), evidence: files, detail: { words:, files:, packages: })
+  end
+end

data/lib/hashira/{analysis → coupling}/roster.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
-class Hashira::Analysis::Roster
+class Hashira::Coupling::Roster
   def initialize(placed)
-    @registry = Hashira::Analysis::ConstantRegistry.new
+    @registry = Hashira::Coupling::ConstantRegistry.new
     @types = Hash.new(0)
     counted = Set.new
     placed.each { |definition, package| admit(definition, package, counted) }

data/lib/hashira/{analysis → coupling}/rule.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-class Hashira::Analysis::Rule
+class Hashira::Coupling::Rule
   def initialize(project, graph)
     @project = project
     @graph = graph

data/lib/hashira/{analysis/resolver.rb → coupling/scope.rb}

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-class Hashira::Analysis::Resolver
+class Hashira::Coupling::Scope
   def initialize(registry, catalog, placement)
     @registry = registry
     @catalog = catalog
@@ -24,5 +24,5 @@ class Hashira::Analysis::Resolver
     segments.length.downto(1).filter_map { @registry.exact(@catalog.strip(entry + segments.first(it))) }.first
   end
 
-  def qualify(found) = (found unless found == Hashira::Analysis::ConstantRegistry::AMBIGUOUS)
+  def qualify(found) = (found unless found == Hashira::Coupling::ConstantRegistry::AMBIGUOUS)
 end

data/lib/hashira/{analysis → coupling}/sdp_check.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-class Hashira::Analysis::SdpCheck
+class Hashira::Coupling::SdpCheck
   def initialize(dependencies, metrics)
     @dependencies = dependencies
     @metrics = metrics

data/lib/hashira/coupling/sdp_violation_findings.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "rule"
+
+class Hashira::Coupling::SdpViolationFindings < Hashira::Coupling::Rule
+  KIND = "sdp_violation"
+
+  def list
+    ranked.map { |from, to| violation(from, to) }
+  end
+
+  private
+
+  def ranked = graph.violations.sort_by { |from, to| instability(from) - instability(to) }
+
+  def violation(from, to)
+    finding(package: from, evidence: graph.evidence(from, to).to_a.first(5), detail: detail(from, to))
+  end
+
+  def detail(from, to)
+    { from:, to:, from_instability: instability(from), to_instability: instability(to) }
+  end
+
+  def instability(package) = metrics[package].instability
+end

data/lib/hashira/coupling/wide_edge_findings.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "rule"
+
+class Hashira::Coupling::WideEdgeFindings < Hashira::Coupling::Rule
+  KIND = "wide_edge"
+
+  WIDTH = 5
+
+  def list
+    graph.edges.select { wide?(it) }.map { entry(it) }
+  end
+
+  private
+
+  def wide?(edge) = graph.constants(edge).size >= WIDTH
+
+  def entry(edge)
+    from, to = edge.deconstruct
+    finding(
+      package: from, digest: "#{from} -> #{to}", evidence: graph.evidence(from, to).to_a.first(4),
+      detail: { from:, to:, constants: graph.constants(edge) }
+    )
+  end
+end

data/lib/hashira/coupling/words.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Hashira::Coupling::Words
+  PATTERN = /\A[a-z][a-z_]*\z/
+
+  module_function
+
+  def list(tree)
+    Hashira::Analysis::NodeWalk.collect(tree).flat_map { entries(it) }.compact.grep(PATTERN).to_set
+  end
+
+  def entries(node)
+    case node
+    when Prism::ArrayNode then node.elements.map { word(it) }
+    when Prism::HashNode then keys(node)
+    else []
+    end
+  end
+
+  def keys(node) = node.elements.grep(Prism::AssocNode).map { word(it.key) }
+
+  def word(node)
+    case node
+    when Prism::SymbolNode, Prism::StringNode then node.unescaped
+    end
+  end
+end

data/lib/hashira/diagram/{renderer.rb → source.rb}

@@ -1,13 +1,13 @@
 # frozen_string_literal: true
 
-class Hashira::Diagram::Renderer
+class Hashira::Diagram::Source
   def initialize(graph, format, io: $stdout)
     @graph = graph
     @format = format
     @io = io
   end
 
-  def display
+  def print
     edges = @graph.weighted
     @io.puts((@format == :dot ? Hashira::Diagram::Dot.new(edges) : Hashira::Diagram::Mermaid.new(edges)).source)
     0

data/lib/hashira/duplication/{analyzer.rb → clones.rb}

@@ -1,17 +1,17 @@
 # frozen_string_literal: true
 
-class Hashira::Duplication::Analyzer
+class Hashira::Duplication::Clones
   def initialize(project, trees, churn)
     @project = project
     @trees = trees
     @churn = churn
   end
 
-  def clusters = @clusters ||= Hashira::Duplication::Clusterer.new(fragments).clusters.sort_by { -it.mass }
+  def clusters = @clusters ||= Hashira::Duplication::Clusters.new(fragments).sorted
 
   def findings = clusters.map { |cluster| Hashira::Duplication::DuplicationFinding.new(cluster, @churn).to_finding }
 
   private
 
-  def fragments = Hashira::Duplication::Extractor.new(@project, @trees).fragments
+  def fragments = Hashira::Duplication::Harvest.new(@project, @trees).fragments
 end

data/lib/hashira/duplication/{clusterer.rb → clusters.rb}

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-class Hashira::Duplication::Clusterer
+class Hashira::Duplication::Clusters
   PREFILTER = 12
   BASE_MASS = 16
   NEAR_MASS = 40
@@ -12,10 +12,10 @@ class Hashira::Duplication::Clusterer
     @sets = Hashira::Duplication::UnionFind.new
   end
 
-  def clusters
+  def sorted
     @fragments.group_by(&:types).each_value { |group| chain(group) }
     Hashira::Duplication::NearMiss.new(@fragments).pairs.each { |left, right| @sets.union(left, right) }
-    Hashira::Duplication::Maximal.new(sized).reduced
+    Hashira::Duplication::Maximal.new(sized).reduced.sort_by { -it.mass }
   end
 
   private

data/lib/hashira/duplication/delta.rb

@@ -1,26 +1,13 @@
 # frozen_string_literal: true
 
 class Hashira::Duplication::Delta
-  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
-
   def initialize(cluster)
     @cluster = cluster
   end
 
-  def summary = ADVICE.fetch(kind)
-
   def kind
     tags = kinds
-    return :identical if tags.empty?
-    return :structure if tags.include?(:structure)
-    tags.size == 1 ? tags.first : :mixed
+    tags.empty? ? :identical : label(tags)
   end
 
   def to_h
@@ -32,6 +19,11 @@ class Hashira::Duplication::Delta
 
   private
 
+  def label(tags)
+    return :structure if tags.include?(:structure)
+    tags.size == 1 ? tags.first : :mixed
+  end
+
   def kinds
     @cluster.others.flat_map { |other| Hashira::Duplication::Variance.new(@cluster.canonical, other).kinds }.uniq
   end

data/lib/hashira/duplication/duplication_finding.rb

@@ -8,21 +8,17 @@ class Hashira::Duplication::DuplicationFinding
 
   def to_finding
     site = @cluster.canonical
-    Hashira::Analysis::Finding.new(
-      kind: "duplication", package: site.location, digest: site.digest,
-      cycle: nil, message:, evidence:
-    )
+    Hashira::Analysis::Finding.new(kind: "duplication", package: site.location, digest: site.digest, detail:, evidence:)
   end
 
   private
 
-  def message
-    "#{@cluster.size} similar fragments (mass #{@cluster.mass}) — #{Hashira::Duplication::Delta.new(@cluster).summary}#{note}"
+  def detail
+    {
+      size: @cluster.size, mass: @cluster.mass,
+      kind: Hashira::Duplication::Delta.new(@cluster).kind, hot: @churn.hot?(@cluster.sites)
+    }
   end
 
   def evidence = @cluster.sites.sort_by(&:rank).map(&:range)
-
-  def note
-    @churn.hot?(@cluster.sites) ? " Both sites change often — fix one, miss the other." : ""
-  end
 end

data/lib/hashira/duplication/{extractor.rb → harvest.rb}

@@ -2,7 +2,7 @@
 
 require "prism"
 
-class Hashira::Duplication::Extractor
+class Hashira::Duplication::Harvest
   WHOLE = [Prism::DefNode, Prism::WhenNode, Prism::RescueNode].freeze
 
   def initialize(project, trees)

data/lib/hashira/duplication/sequence.rb

@@ -26,7 +26,9 @@ class Hashira::Duplication::Sequence
 
   def lengths(segment) = MIN_STATEMENTS..[segment.size, MAX_STATEMENTS].min
 
-  def slide(segment, length) = (0..(segment.size - length)).map { fragment(segment[it, length]) }
+  def slide(segment, length) = spans(segment, length).map { fragment(segment[it, length]) }
+
+  def spans(segment, length) = 0..(segment.size - length)
 
   def fragment(roots) = Hashira::Duplication::Fragment.new(@file, roots)
 end

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,34 @@
 # frozen_string_literal: true
 
 require "prism"
+require_relative "coupling/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
 
   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 +39,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