hashira 0.3.0 → 0.5.0

data/lib/hashira/report/metrics_table.rb

@@ -1,37 +1,50 @@
 # frozen_string_literal: true
 
-module Hashira
-  module Report
-    class MetricsTable
-      def initialize(graph, io: $stdout)
-        @graph = graph
-        @io = io
-      end
-
-      def print
-        heading
-        by_instability.each { |package, metric| @io.puts row(package, metric) }
-        legend
-      end
-
-      private
-
-      def by_instability = @graph.metrics.sort_by { |_package, metric| metric.instability }
-
-      def heading
-        @io.puts format("%-12s %3s %3s %3s %5s  %-3s", *%w[package TC Ca Ce I Cyc])
-        @io.puts "-" * 40
-      end
-
-      def row(package, metric)
-        cyclic = @graph.cyclic?(package) ? "YES" : "-"
-        format("%-12s %3d %3d %3d %5.2f  %-3s", package, *metric.to_h.values, cyclic)
-      end
-
-      def legend
-        @io.puts "\nLegend: TC total types, Ca afferent (incoming), Ce efferent (outgoing),"
-        @io.puts "        I=Ce/(Ce+Ca) instability (0=maximally stable, 1=maximally unstable)\n\n"
-      end
-    end
+class Hashira::Report::MetricsTable
+  def initialize(graph, io: $stdout)
+    @graph = graph
+    @io = io
+  end
+
+  LIMIT = 25
+
+  def print
+    heading
+    kept.each { |package, metric| @io.puts(row(package, metric)) }
+    note unless spared.empty?
+    legend
+  end
+
+  private
+
+  def ranked = @graph.metrics.sort_by { |_package, metric| metric.instability }
+
+  def split = @split ||= (ranked.size > LIMIT ? ranked.partition { |_package, metric| !leaf?(metric) } : [ranked, []])
+
+  def kept = split.first
+
+  def spared = split.last
+
+  def leaf?(metric) = metric.types <= 1 && metric.efferent.zero? && metric.afferent <= 1
+
+  def note
+    @io.puts("  + #{spared.size} single-type leaf packages (TC ≤ 1, Ca ≤ 1, Ce = 0) — hidden for brevity")
+  end
+
+  def heading
+    @io.puts(format("%-12s %3s %3s %3s %5s  %-3s", *%w[package TC Ca Ce I Cyc]))
+    @io.puts("-" * 40)
+  end
+
+  def row(package, metric)
+    format(
+      "%-12s %3d %3d %3d %5.2f  %-3s", package, *metric.to_h.values,
+      (@graph.cycles.through?(package) ? "YES" : "-")
+    )
+  end
+
+  def legend
+    @io.puts("\nLegend: TC total types, Ca afferent (incoming), Ce efferent (outgoing),")
+    @io.puts("        I=Ce/(Ce+Ca) instability (0=maximally stable, 1=maximally unstable)\n\n")
   end
 end

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/report/text.rb

@@ -1,68 +1,75 @@
 # frozen_string_literal: true
 
-module Hashira
-  module Report
-    class Text
-      def initialize(view, io: $stdout)
-        @view = view
-        @io = io
-      end
+class Hashira::Report::Text
+  def initialize(view, io: $stdout)
+    @view = view
+    @io = io
+  end
 
-      def print
-        coupling_sections if @view.graph
-        complexity_section if @view.complexity
-        hotspot_section if @view.hotspots
-        findings_section
-        0
-      end
+  def print
+    coupling if @view.graph
+    complexity if @view.complexity
+    hotspots if @view.hotspots
+    findings
+    0
+  end
 
-      private
+  private
 
-      def coupling_sections
-        graph = @view.graph
-        header(graph)
-        MetricsTable.new(graph, io: @io).print
-        DependencyMap.new(graph, io: @io).print
-      end
+  def coupling
+    graph = @view.graph
+    header(graph)
+    Hashira::Report::MetricsTable.new(graph, io: @io).print
+    Hashira::Report::DependencyMap.new(graph, io: @io).print
+    folded(graph.folds)
+  end
+
+  def folded(folds)
+    return if folds.empty?
+    @io.puts("\nFolded (single-type classes joined to their base or domain):")
+    folds.each { @io.puts("  #{it[:from]} -> #{it[:to]} (#{it[:via]})") }
+  end
 
-      def complexity_section = ComplexityTable.new(@view.complexity, io: @io).print
+  def complexity = Hashira::Report::ComplexityTable.new(@view.complexity, io: @io).print
 
-      def hotspot_section = HotspotTable.new(@view.hotspots, io: @io).print
+  def hotspots = Hashira::Report::HotspotTable.new(@view.hotspots, io: @io).print
 
-      def header(graph)
-        project = @view.project
-        packages = graph.packages.size
-        @io.puts "Package (layer) metrics for #{project.label}  " \
-                 "(#{packages} packages, #{project.files.size} files)\n\n"
-        single_package_note if packages == 1
-      end
+  def header(graph)
+    packages = graph.packages.size
+    @io.puts(banner(packages))
+    caveat if packages == 1
+  end
 
-      def single_package_note
-        @io.puts "Only one package found — there are no boundaries to analyze. " \
-                 "Pass subdirectories to set them (e.g. hashira lib/gem/*/).\n\n"
-      end
+  def banner(packages)
+    "Package (layer) metrics for #{@view.project.label}  (#{packages} packages, #{total} files)\n\n"
+  end
 
-      def findings_section
-        all = @view.findings.all
-        @io.puts "\nFindings (#{all.size}):"
-        print_findings(all)
-        accepted_section
-        @io.puts "\n  Full evidence + machine format: hashira --json" unless all.empty?
-      end
+  def total = @view.project.files.size
 
-      def print_findings(all)
-        return @io.puts "  none ✓ — structure is healthy" if all.empty?
+  def caveat
+    @io.puts(
+      "Only one package found — there are no boundaries to analyze. " \
+        "Pass subdirectories to set them (e.g. hashira lib/gem/*/).\n\n"
+    )
+  end
 
-        all.each { FindingLines.new(it, indent: "  ", io: @io).print_with_overflow }
-      end
+  def findings
+    all = @view.findings.all
+    @io.puts("\nFindings (#{all.size}):")
+    list(all)
+    accepted
+    @io.puts("\n  Full evidence + machine format: hashira --json") unless all.empty?
+  end
 
-      def accepted_section
-        accepted = @view.findings.accepted
-        return if accepted.empty?
+  def list(all)
+    return @io.puts("  none ✓ — structure is healthy") if all.empty?
+    all.each { Hashira::Report::FindingLines.new(it, indent: "  ", io: @io).emit }
+  end
 
-        @io.puts "\nAccepted (#{accepted.size}):"
-        accepted.each { |finding, reason| @io.puts "  ~ #{finding.kind}/#{finding.package} — #{reason}" }
-      end
-    end
+  def accepted
+    accepted = @view.findings.accepted
+    return if accepted.empty?
+    @io.puts("\nAccepted (#{accepted.size}):")
+    accepted.each { |finding, reason| @io.puts("  ~ #{finding.kind}/#{finding.package} — #{reason}") }
   end
 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,30 @@
+# frozen_string_literal: true
+
+class Hashira::Smells::Check
+  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.name.split("::").last.gsub(/(?<=[a-z])(?=[A-Z])/, "_").downcase
+
+  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,30 @@
+# frozen_string_literal: true
+
+class Hashira::Smells::DataClump < Hashira::Smells::Check
+  MAX_COPIES = 2
+
+  MIN_SIZE = 2
+
+  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