hashira 0.4.0 → 0.5.1

data/lib/hashira/cli/usage.rb

@@ -1,43 +1,42 @@
 # frozen_string_literal: true
 
+require_relative "flags"
+
 module Hashira::CLI::Usage
-  TEXT = <<~HELP
+  PAGES = %i[help version].freeze
+
+  HEADER = <<~TEXT
     Usage: hashira [DIRECTORY ...] [options]
 
-    Coupling, cognitive-complexity, and duplication metrics for Ruby, via
-    Prism, rolled up per file as a ranked list of hotspots. With no
-    directory, auto-detects lib/<gem>.
+    Coupling, cognitive-complexity, duplication, and code-smell metrics
+    for Ruby, via Prism, rolled up per file as a ranked list of hotspots.
+    With no directory, auto-detects lib/<gem>.
 
     Options:
-      --format FORMAT      text (default), json, dot, or mermaid
-      --json               shorthand for --format json
-      --fail-on KINDS      exit 1 if findings exist; comma-separated
-                           kinds: cycles, sdp, complexity, duplication
-      --skip ANALYZERS     drop an analyzer; comma-separated: coupling, complexity, duplication
-      --package-by WHAT    group coupling by: auto, folder, or namespace
-                           (top-level constant). Default auto: namespace for
-                           Rails apps (config/application.rb in or beside the
-                           analyzed directory), folder otherwise
-      --ratchet            fail when edges or findings appear that the
-                           baseline lacks
-      --update-baseline    record the current edges and findings
-      --baseline PATH      baseline file (default: hashira_baseline.json)
-      -h, --help           print this help
-      --version            print the version
+  TEXT
+
+  FOOTER = <<~TEXT
 
     Findings accepted by design can be recorded in the baseline as
       "accepted": [{"kind": "...", "package": "...", "reason": "..."}]
     — they leave reports and gates, keeping a one-line reminder each.
     Clones are named by "digest" instead of "package", so an acceptance
     survives the lines above it moving. Read digests from --json.
-  HELP
+  TEXT
 
   module_function
 
-  def help = emit(TEXT)
+  def help = emit(HEADER + options + FOOTER)
 
   def version = emit("hashira #{Hashira::VERSION}")
 
+  def options = Hashira::CLI::FLAGS.map { rows(it) }.join
+
+  def rows(flag)
+    first, *rest = flag.text
+    ["  #{flag.label.ljust(21)}#{first}\n", *rest.map { "#{" " * 23}#{it}\n" }].join
+  end
+
   def emit(output)
     puts(output)
     0

data/lib/hashira/cli.rb

@@ -8,7 +8,7 @@ class Hashira::CLI
     failure(error)
   end
 
-  def self.usage?(options) = %i[help version].include?(options.mode)
+  def self.usage?(options) = Usage::PAGES.include?(options.mode)
 
   def self.failure(error)
     warn("hashira: #{error.message}")

data/lib/hashira/complexity/boolean_run.rb

@@ -5,14 +5,16 @@ class Hashira::Complexity::BooleanRun
     @scorer = scorer
   end
 
-  def apply(node, nesting)
+  def apply(node)
     @scorer.add(node, 1, "boolean")
-    operands(node).each { @scorer.visit(it, nesting) }
+    operands(node).each { @scorer.visit(it) }
   end
 
   private
 
   def operands(node)
-    node.compact_child_nodes.flat_map { it.instance_of?(node.class) ? operands(it) : [it] }
+    node.compact_child_nodes.flat_map { kin?(it, node) ? operands(it) : [it] }
   end
+
+  def kin?(child, node) = child.instance_of?(node.class)
 end

data/lib/hashira/complexity/cognitive_score.rb

@@ -27,41 +27,48 @@ class Hashira::Complexity::CognitiveScore
   def initialize(def_node)
     @increments = []
     @calls = 0
-    visit(def_node.body, 0)
+    @nesting = 0
+    visit(def_node.body)
   end
 
-  attr_reader :increments, :calls
+  attr_reader :increments, :calls, :nesting
 
   def total = @increments.sum(&:cost)
 
-  def visit(node, nesting)
+  def visit(node)
     return unless node
-    __send__(HANDLERS.fetch(node.class, :descend), node, nesting)
+    __send__(HANDLERS.fetch(node.class, :descend), node)
   end
 
   def add(node, cost, label)
     @increments << Hashira::Complexity::Increment.new(line: node.location.start_line, cost:, label:)
   end
 
+  def deeper
+    @nesting += 1
+    yield
+    @nesting -= 1
+  end
+
   private
 
-  def descend(node, nesting) = node.compact_child_nodes.each { visit(it, nesting) }
+  def descend(node) = node.compact_child_nodes.each { visit(it) }
 
-  def on_call(node, nesting)
+  def on_call(node)
     @calls += 1
-    descend(node, nesting)
+    descend(node)
   end
 
-  def on_block(node, nesting) = node.compact_child_nodes.each { visit(it, nesting + 1) }
+  def on_block(node) = deeper { descend(node) }
 
-  def on_nester(node, nesting)
-    add(node, 1 + nesting, LABELS.fetch(node.class))
-    node.compact_child_nodes.each { visit(it, nesting + 1) }
+  def on_nester(node)
+    add(node, 1 + @nesting, LABELS.fetch(node.class))
+    deeper { descend(node) }
   end
 
-  def on_if(node, nesting) = Hashira::Complexity::IfChain.new(self).apply(node, nesting)
+  def on_if(node) = Hashira::Complexity::IfChain.new(self).apply(node)
 
-  def on_begin(node, nesting) = Hashira::Complexity::RescueScan.new(self).apply(node, nesting)
+  def on_begin(node) = Hashira::Complexity::RescueScan.new(self).apply(node)
 
-  def on_boolean(node, nesting) = Hashira::Complexity::BooleanRun.new(self).apply(node, nesting)
+  def on_boolean(node) = Hashira::Complexity::BooleanRun.new(self).apply(node)
 end

data/lib/hashira/complexity/if_chain.rb

@@ -7,34 +7,34 @@ class Hashira::Complexity::IfChain
     @scorer = scorer
   end
 
-  def apply(node, nesting)
-    return ternary(node, nesting) unless node.if_keyword
-    branch(node, 1 + nesting, nesting, "if")
+  def apply(node)
+    return ternary(node) unless node.if_keyword
+    branch(node, 1 + @scorer.nesting, "if")
   end
 
   private
 
-  def branch(node, cost, nesting, label)
+  def branch(node, cost, label)
     @scorer.add(node, cost, label)
-    @scorer.visit(node.predicate, nesting)
-    @scorer.visit(node.statements, nesting + 1)
-    tail(node.subsequent, nesting)
+    @scorer.visit(node.predicate)
+    @scorer.deeper { @scorer.visit(node.statements) }
+    tail(node.subsequent)
   end
 
-  def tail(node, nesting)
+  def tail(node)
     case node
-    when Prism::IfNode then branch(node, 1, nesting, "elsif")
-    when Prism::ElseNode then otherwise(node, nesting)
+    when Prism::IfNode then branch(node, 1, "elsif")
+    when Prism::ElseNode then otherwise(node)
     end
   end
 
-  def otherwise(node, nesting)
+  def otherwise(node)
     @scorer.add(node, 1, "else")
-    @scorer.visit(node.statements, nesting + 1)
+    @scorer.deeper { @scorer.visit(node.statements) }
   end
 
-  def ternary(node, nesting)
+  def ternary(node)
     @scorer.add(node, 1, "ternary")
-    node.compact_child_nodes.each { @scorer.visit(it, nesting) }
+    node.compact_child_nodes.each { @scorer.visit(it) }
   end
 end

data/lib/hashira/complexity/method_finding.rb

@@ -1,33 +1,20 @@
 # frozen_string_literal: true
 
 class Hashira::Complexity::MethodFinding
-  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
+  KIND = "complexity"
 
   def initialize(score)
     @score = score
   end
 
   def to_finding
-    Hashira::Analysis::Finding.new(kind: "complexity", package: @score.subject, cycle: nil, message:, evidence:)
+    Hashira::Analysis::Finding.new(kind: KIND, package: @score.subject, detail:, evidence:)
   end
 
   private
 
-  def message
-    "#{@score.subject} — cognitive #{@score.cognitive}, #{@score.calls} calls " \
-      "(#{@score.file}:#{@score.line}). #{advice}"
+  def detail
+    { cognitive: @score.cognitive, calls: @score.calls, site: "#{@score.file}:#{@score.line}", dominant: }
   end
 
   def evidence
@@ -39,8 +26,6 @@ class Hashira::Complexity::MethodFinding
     "#{label} +#{incs.sum(&:cost)} (line#{"s" if lines.size > 1} #{lines.join(", ")})"
   end
 
-  def advice = ADVICE.fetch(dominant)
-
   def dominant
     @score.increments.group_by(&:label).transform_values { it.sum(&:cost) }.max_by(&:last).first
   end

data/lib/hashira/complexity/rescue_scan.rb

@@ -5,19 +5,19 @@ class Hashira::Complexity::RescueScan
     @scorer = scorer
   end
 
-  def apply(node, nesting)
-    @scorer.visit(node.statements, nesting)
-    clauses(node.rescue_clause, nesting)
-    @scorer.visit(node.else_clause, nesting)
-    @scorer.visit(node.ensure_clause, nesting)
+  def apply(node)
+    @scorer.visit(node.statements)
+    clauses(node.rescue_clause)
+    @scorer.visit(node.else_clause)
+    @scorer.visit(node.ensure_clause)
   end
 
   private
 
-  def clauses(node, nesting)
+  def clauses(node)
     return unless node
-    @scorer.add(node, 1 + nesting, "rescue")
-    @scorer.visit(node.statements, nesting + 1)
-    clauses(node.subsequent, nesting)
+    @scorer.add(node, 1 + @scorer.nesting, "rescue")
+    @scorer.deeper { @scorer.visit(node.statements) }
+    clauses(node.subsequent)
   end
 end

data/lib/hashira/complexity/{analyzer.rb → scores.rb}

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-class Hashira::Complexity::Analyzer
+class Hashira::Complexity::Scores
   THRESHOLD = 10
 
   def initialize(project, trees)
@@ -8,7 +8,7 @@ class Hashira::Complexity::Analyzer
     @scores = trees.flat_map { |path, tree| harvest(path, tree) }
   end
 
-  def methods = @scores.sort_by { -it.cognitive }
+  def ranked = @scores.sort_by { -it.cognitive }
 
   def classes = Hashira::Complexity::Rollup.new(@scores).classes.sort_by { -it.cognitive }
 
@@ -16,7 +16,7 @@ class Hashira::Complexity::Analyzer
 
   private
 
-  def flagged = methods.select { it.cognitive >= THRESHOLD }
+  def flagged = ranked.select { it.cognitive >= THRESHOLD }
 
   def harvest(path, tree)
     rel = @project.relative(path)
@@ -32,12 +32,13 @@ class Hashira::Complexity::Analyzer
   end
 
   def score(rel, full, node)
-    score = Hashira::Complexity::CognitiveScore.new(node)
     Hashira::Complexity::MethodScore.new(
       subject: subject(full, node), file: rel, line: node.location.start_line,
-      cognitive: score.total, calls: score.calls, increments: score.increments
+      **tallies(Hashira::Complexity::CognitiveScore.new(node))
     )
   end
 
+  def tallies(score) = { cognitive: score.total, calls: score.calls, increments: score.increments }
+
   def subject(full, node) = "#{full.join("::")}#{node.receiver ? "." : "#"}#{node.name}"
 end

data/lib/hashira/coupling/audiences.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+class Hashira::Coupling::Audiences
+  MIN = 2
+
+  Part = Data.define(:users, :constants, :shared)
+
+  def initialize(usage)
+    @usage = usage
+  end
+
+  def split? = parts.size >= 2
+
+  def parts = @parts ||= [common, *slices].compact.select { it.constants.size >= MIN }
+
+  private
+
+  def clients = @clients ||= @usage.keys.sort
+
+  def shared = @shared ||= tally.select { |_constant, users| users.size * 2 > clients.size }.keys.to_set
+
+  def tally
+    clients.each_with_object(Hash.new { |hash, key| hash[key] = [] }) do |client, seen|
+      @usage[client].each { seen[it] << client }
+    end
+  end
+
+  def common
+    return if shared.empty?
+    Part.new(users: clients.select { @usage[it].intersect?(shared) }, constants: shared.sort, shared: true)
+  end
+
+  def slices
+    groups.sort_by(&:first).map { |members| Part.new(users: members, constants: pooled(members).sort, shared: false) }
+  end
+
+  def pooled(members) = members.reduce(Set.new) { |pool, client| pool | residue(client) }
+
+  def residue(client) = @usage[client] - shared
+
+  def groups
+    clients.reduce([]) do |formed, client|
+      linked, apart = formed.partition { |members| joined?(members, client) }
+      apart + [linked.flatten + [client]]
+    end
+  end
+
+  def joined?(members, client) = members.any? { residue(it).intersect?(residue(client)) }
+end

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

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
-class Hashira::Analysis::Catalog
+class Hashira::Coupling::Catalog
   include Enumerable
 
   def initialize(definitions)
     @definitions = definitions
-    @naming = Hashira::Analysis::Naming.new(definitions)
+    @naming = Hashira::Coupling::Naming.new(definitions)
     @entries = definitions.map { |node, full, folder| entry(node, full, folder) }
   end
 
@@ -22,6 +22,6 @@ class Hashira::Analysis::Catalog
   private
 
   def entry(node, full, folder)
-    Hashira::Analysis::Definition.new(node:, path: @naming.strip(full), folder:)
+    Hashira::Coupling::Definition.new(node:, path: @naming.strip(full), folder:)
   end
 end

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

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
-class Hashira::Analysis::Census
+class Hashira::Coupling::Census
   def initialize(project, trees, packaging: :folder)
-    @catalog = Hashira::Analysis::Catalog.new(Hashira::Analysis::Definitions.new(project, trees))
-    @placement = Hashira::Analysis::Placement.build(packaging, project, @catalog)
-    @folding = Hashira::Analysis::NoFolding
+    @catalog = Hashira::Coupling::Catalog.new(Hashira::Coupling::Definitions.new(project, trees))
+    @placement = Hashira::Coupling::Placement.build(packaging, project, @catalog)
+    @folding = Hashira::Coupling::NoFolding
     @roster = tally
     settle
   end
@@ -23,16 +23,25 @@ class Hashira::Analysis::Census
 
   def folds = @folding.disclosed
 
-  def resolve(segments, nesting = []) = resolver.resolve(segments, nesting)
+  def strip(segments) = @catalog.strip(segments)
 
-  def pinpoint(segments) = resolver.pinpoint(segments)
+  def holder(segments)
+    path = strip(segments)
+    (path.length.downto(1).map { path.first(it) }.find { type?(it) } || path).join("::")
+  end
+
+  def resolve(segments, nesting = []) = scope.resolve(segments, nesting)
+
+  def pinpoint(segments) = scope.pinpoint(segments)
 
   def charge(file, nesting) = translate(@placement.charge(file, nesting))
 
   private
 
+  def type?(segments) = @roster.type?(segments)
+
   def tally
-    Hashira::Analysis::Roster.new(@placement.placed.map { |definition, package| [definition, translate(package)] })
+    Hashira::Coupling::Roster.new(@placement.placed.map { |definition, package| [definition, translate(package)] })
   end
 
   def settle
@@ -42,5 +51,5 @@ class Hashira::Analysis::Census
 
   def translate(package) = @folding.map.fetch(package, package)
 
-  def resolver = Hashira::Analysis::Resolver.new(@roster.registry, @catalog, @placement)
+  def scope = Hashira::Coupling::Scope.new(@roster.registry, @catalog, @placement)
 end

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

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-class Hashira::Analysis::ConstantRegistry
+class Hashira::Coupling::ConstantRegistry
   AMBIGUOUS = Object.new.freeze
 
   def initialize
@@ -16,10 +16,9 @@ class Hashira::Analysis::ConstantRegistry
     (1...path.length).each { claim(@shorthand, path.drop(it), package) }
   end
 
-  def package(path)
-    found = anchored(path) || enclosing(path)
-    found unless found == AMBIGUOUS
-  end
+  def package(path) = settle(anchored(path) || enclosing(path))
+
+  def rooted(path) = settle(@origins[path.join("::")] || enclosing(path))
 
   def exact(path) = @origins[path.join("::")]
 
@@ -32,12 +31,18 @@ class Hashira::Analysis::ConstantRegistry
     claims[key] = claims.fetch(key, package) == package ? package : AMBIGUOUS
   end
 
+  def settle(found) = (found unless found == AMBIGUOUS)
+
   def anchored(path)
     key = path.join("::")
     @origins[key] || @shorthand[key]
   end
 
   def enclosing(path)
-    (path.length - 1).downto(1).filter_map { @origins[path.first(it).join("::")] }.first
+    prefixes(path).filter_map { @origins[it] }.first
+  end
+
+  def prefixes(path)
+    (path.length - 1).downto(1).map { path.first(it).join("::") }
   end
 end

data/lib/hashira/coupling/cycle_findings.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative "rule"
+
+class Hashira::Coupling::CycleFindings < Hashira::Coupling::Rule
+  KIND = "cycle"
+
+  def list
+    loops.map { entry(it) }
+  end
+
+  private
+
+  def loops
+    cycles = graph.cycles
+    graph.packages.select { cycles.through?(it) }.sort.map { cycles.path(it) }.uniq { it[..-2].sort }
+  end
+
+  def entry(path)
+    finding(package: path.first, cycle: path, evidence: evidence(path), detail: detail(graph.cycles.weakest(path)))
+  end
+
+  def detail(weak)
+    from, to = weak
+    { weak:, weight: graph.weight(from, to) }
+  end
+
+  def evidence(path)
+    path.each_cons(2).flat_map { |from, to| graph.evidence(from, to).to_a.first(2) }
+  end
+end

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

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

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

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-class Hashira::Analysis::Cycles
+class Hashira::Coupling::Cycles
   def initialize(dependencies, graph)
     @dependencies = dependencies
     @graph = graph
@@ -8,7 +8,7 @@ class Hashira::Analysis::Cycles
 
   def through?(package) = !!path(package)
 
-  def path(package) = Hashira::Analysis::CycleSearch.new(@dependencies, package).path
+  def path(package) = Hashira::Coupling::CycleSearch.new(@dependencies, package).path
 
   def weakest(trail) = trail.each_cons(2).min_by { |from, to| @graph.weight(from, to) }
 end

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

@@ -3,7 +3,7 @@
 require "prism"
 
 module Hashira
-  module Analysis
+  module Coupling
     Definition =
       Data.define(:node, :path, :folder) do
         def name = path.first
@@ -16,7 +16,11 @@ module Hashira
 
         def superclass = node.superclass
 
-        def counted? = klass? || !Hashira::Analysis::Syntax.direct(node).empty?
+        def module? = node.is_a?(Prism::ModuleNode)
+
+        def type? = klass? || module?
+
+        def counted? = klass? || (module? && !Hashira::Analysis::Syntax.direct(node).empty?)
       end
   end
 end

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

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-class Hashira::Analysis::Definitions
+class Hashira::Coupling::Definitions
   include Enumerable
 
   def initialize(project, trees)
@@ -26,6 +26,9 @@ class Hashira::Analysis::Definitions
 
   def scan(file, tree)
     package = @project.package(file)
-    Hashira::Analysis::TypeWalk.each(tree, roots: roots) { |node, full| yield(node, full, package) }
+    Hashira::Analysis::TypeWalk.each(tree, roots: roots) do |node, full|
+      yield(node, full, package)
+      Hashira::Analysis::Syntax.constants(node).each { yield(it, full + [it.name.to_s], package) }
+    end
   end
 end

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Hashira
-  module Analysis
+  module Coupling
     Edge =
       Data.define(:from, :to) do
         def to_s = "#{from} -> #{to}"

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

@@ -1,19 +1,18 @@
 # frozen_string_literal: true
 
-class Hashira::Analysis::EdgeMap
-  def initialize(project, census)
-    @project = project
+class Hashira::Coupling::EdgeMap
+  def initialize(census)
     @census = census
     @dependencies = sets
     @evidence = sets
+    @usage = sets
   end
 
-  attr_reader :dependencies, :evidence
+  attr_reader :dependencies, :evidence, :usage
 
-  def record(file, tree)
-    source = @project.relative(file)
-    Hashira::Analysis::References.sightings(tree, @census.roots).each do |segments, line, nesting, home|
-      note(@census.charge(file, home), locate(segments, nesting), "#{source}:#{line}: #{segments.join("::")}")
+  def record(source, file, tree)
+    Hashira::Coupling::References.sightings(tree, @census.roots).each do |segments, line, nesting, home|
+      note(@census.charge(file, home), locate(segments, nesting), segments, "#{source}:#{line}")
     end
   end
 
@@ -25,9 +24,10 @@ class Hashira::Analysis::EdgeMap
     nesting ? @census.resolve(segments, nesting) : @census.pinpoint(segments)
   end
 
-  def note(from, to, sighting)
+  def note(from, to, segments, site)
     return unless to && to != from
     @dependencies[from] << to
-    @evidence[[from, to]] << sighting
+    @evidence[[from, to]] << "#{site}: #{segments.join("::")}"
+    @usage[[from, to]] << @census.holder(segments)
   end
 end

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

@@ -2,7 +2,7 @@
 
 require_relative "placement"
 
-class Hashira::Analysis::FolderPlacement < Hashira::Analysis::Placement
+class Hashira::Coupling::FolderPlacement < Hashira::Coupling::Placement
   def mode = :folder
 
   def placed = catalog.map { [it, it.folder] }
@@ -13,5 +13,5 @@ class Hashira::Analysis::FolderPlacement < Hashira::Analysis::Placement
 
   def skip?(_segments) = false
 
-  def folding(_census) = Hashira::Analysis::NoFolding
+  def folding(_census) = Hashira::Coupling::NoFolding
 end