hashira 0.4.0 → 0.5.1

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

@@ -2,7 +2,7 @@
 
 require "prism"
 
-class Hashira::Analysis::Folding
+class Hashira::Coupling::Folding
   SUFFIXES = %w[Resource Serializer Policy Decorator].freeze
 
   def initialize(definitions, census, suffixes: [])
@@ -32,10 +32,12 @@ class Hashira::Analysis::Folding
   def pair(name, stem) = ([name, stem] if stem && @census.packages.include?(stem))
 
   def crop(name)
-    suffix = @suffixes.find { name.end_with?(it) && name != it }
+    suffix = @suffixes.find { trims?(name, it) }
     suffix && name.delete_suffix(suffix)
   end
 
+  def trims?(name, suffix) = name.end_with?(suffix) && name != suffix
+
   def singles = @singles ||= lone.group_by(&:name).transform_values { it.find(&:superclass) || it.last }
 
   def lone = @definitions.select(&:singular?).reject { anchored.include?(it.name) }

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

@@ -1,14 +1,17 @@
 # frozen_string_literal: true
 
-class Hashira::Analysis::Graph
+class Hashira::Coupling::Graph
   def initialize(project, trees, census)
     @census = census
-    @map = Hashira::Analysis::EdgeMap.new(project, census)
-    trees.each { |file, tree| @map.record(file, tree) }
-    @cycles = Hashira::Analysis::Cycles.new(@map.dependencies, self)
+    @trees = trees
+    @map = Hashira::Coupling::EdgeMap.new(census)
+    trees.each { |file, tree| @map.record(project.relative(file), file, tree) }
+    @cycles = Hashira::Coupling::Cycles.new(@map.dependencies, self)
   end
 
-  attr_reader :cycles
+  attr_reader :cycles, :trees
+
+  def charge(file) = @census.charge(file, [])
 
   def packages = (@census.packages | @map.dependencies.keys)
 
@@ -21,7 +24,7 @@ class Hashira::Analysis::Graph
   def incoming(package) = packages.select { dependencies[it].include?(package) }.sort
 
   def edges
-    dependencies.sort.flat_map { |from, tos| tos.sort.map { Hashira::Analysis::Edge.new(from:, to: it) } }
+    dependencies.sort.flat_map { |from, tos| tos.sort.map { Hashira::Coupling::Edge.new(from:, to: it) } }
   end
 
   def weighted
@@ -33,8 +36,15 @@ class Hashira::Analysis::Graph
 
   def evidence(from, to) = @map.evidence[[from, to]]
 
+  def usage(package) = incoming(package).to_h { [it, @map.usage[[it, package]]] }
+
+  def constants(edge)
+    from, to = edge.deconstruct
+    @map.usage[[from, to]].sort
+  end
+
   def metric(package)
-    Hashira::Analysis::Metric.new(
+    Hashira::Coupling::Metric.new(
       types: @census.types[package],
       afferent: incoming(package).size,
       efferent: dependencies[package].size
@@ -43,7 +53,7 @@ class Hashira::Analysis::Graph
 
   def metrics = packages.to_h { [it, metric(it)] }
 
-  def violations = Hashira::Analysis::SdpCheck.new(dependencies, metrics).violations
+  def violations = Hashira::Coupling::SdpCheck.new(dependencies, metrics).violations
 
   def weight(from, to) = evidence(from, to).size
 

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Hashira
-  module Analysis
+  module Coupling
     Metric =
       Data.define(:types, :afferent, :efferent) do
         def instability

data/lib/hashira/coupling/mixed_audience_findings.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "rule"
+
+class Hashira::Coupling::MixedAudienceFindings < Hashira::Coupling::Rule
+  KIND = "mixed_audience"
+
+  def list
+    graph.packages.sort.filter_map { verdict(it) }
+  end
+
+  private
+
+  def verdict(package)
+    audiences = Hashira::Coupling::Audiences.new(graph.usage(package))
+    detail(package, audiences.parts) if audiences.split?
+  end
+
+  def detail(package, parts)
+    finding(
+      package:, evidence: parts.flat_map do
+        sightings(package, it).first(2)
+      end, detail: { parts: parts.map(&:to_h) }
+    )
+  end
+
+  def sightings(package, part)
+    part.users.flat_map { |client| graph.evidence(client, package).to_a.select { mentions?(it, part.constants) } }
+  end
+
+  def mentions?(line, constants) = constants.any? { line.end_with?(": #{it}", "::#{it}") }
+end

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

@@ -2,7 +2,7 @@
 
 require_relative "placement"
 
-class Hashira::Analysis::NamespacePlacement < Hashira::Analysis::Placement
+class Hashira::Coupling::NamespacePlacement < Hashira::Coupling::Placement
   RAILS_BASES =
     %w[ApplicationRecord ApplicationController ApplicationJob ApplicationMailer
       ApplicationHelper ApplicationCable ApplicationResource ApplicationSerializer
@@ -20,9 +20,9 @@ class Hashira::Analysis::NamespacePlacement < Hashira::Analysis::Placement
 
   def skip?(segments) = project.rails? && RAILS_BASES.include?(segments.first)
 
-  def folding(census) = Hashira::Analysis::Folding.new(catalog, census, suffixes: suffixes)
+  def folding(census) = Hashira::Coupling::Folding.new(catalog, census, suffixes: suffixes)
 
   private
 
-  def suffixes = project.rails? ? Hashira::Analysis::Folding::SUFFIXES : []
+  def suffixes = project.rails? ? Hashira::Coupling::Folding::SUFFIXES : []
 end

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Hashira
-  module Analysis
+  module Coupling
     module NamespacePrefix
       module_function
 

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

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
-class Hashira::Analysis::Naming
+class Hashira::Coupling::Naming
   def initialize(definitions)
-    @segments = Hashira::Analysis::NamespacePrefix.infer(definitions)
+    @segments = Hashira::Coupling::NamespacePrefix.infer(definitions)
   end
 
   attr_reader :segments

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Hashira
-  module Analysis
+  module Coupling
     module NoFolding
       module_function
 

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

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
-class Hashira::Analysis::Placement
+class Hashira::Coupling::Placement
   def self.build(packaging, project, catalog)
     {
-      folder: Hashira::Analysis::FolderPlacement,
-      namespace: Hashira::Analysis::NamespacePlacement
+      folder: Hashira::Coupling::FolderPlacement,
+      namespace: Hashira::Coupling::NamespacePlacement
     }.fetch(packaging).new(project, catalog)
   end
 

data/lib/hashira/coupling/references.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "prism"
+
+class Hashira::Coupling::References
+  def self.list(tree) = new.sightings(tree).map(&:first)
+
+  def self.sightings(tree, roots = nil) = new(roots).sightings(tree)
+
+  def initialize(roots = nil)
+    @roots = roots
+    @found = []
+    @scopes = [[]]
+  end
+
+  def sightings(tree)
+    collect(tree)
+    @found
+  end
+
+  private
+
+  def nesting = @scopes.last
+
+  def collect(node, home = nesting)
+    return unless node
+    return @found << sighting(node, home) if constant?(node)
+    return enter(node) if definition?(node)
+    node.compact_child_nodes.each { collect(it, home) }
+  end
+
+  def sighting(node, home)
+    [syntax.segments(node), node.location.start_line, syntax.cbase?(node) ? nil : nesting, home]
+  end
+
+  def syntax = Hashira::Analysis::Syntax
+
+  def constant?(node) = node.is_a?(Prism::ConstantPathNode) || node.is_a?(Prism::ConstantReadNode)
+
+  def definition?(node) = node.is_a?(Prism::ClassNode) || node.is_a?(Prism::ModuleNode)
+
+  def enter(node)
+    opened = nesting + [anchor(node)]
+    collect(node.superclass, opened) if node.is_a?(Prism::ClassNode)
+    inside(opened) { collect(node.body) }
+  end
+
+  def anchor(node) = syntax.anchor(nesting, syntax.segments(node.constant_path), @roots)
+
+  def inside(scope)
+    @scopes << scope
+    yield
+    @scopes.pop
+  end
+end

data/lib/hashira/coupling/report.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "cycle_findings"
+require_relative "mixed_audience_findings"
+require_relative "roll_call_findings"
+require_relative "sdp_violation_findings"
+require_relative "wide_edge_findings"
+
+class Hashira::Coupling::Report
+  RULES = [
+    Hashira::Coupling::CycleFindings, Hashira::Coupling::SdpViolationFindings,
+    Hashira::Coupling::MixedAudienceFindings, Hashira::Coupling::WideEdgeFindings,
+    Hashira::Coupling::RollCallFindings
+  ].freeze
+
+  def initialize(project, trees, packaging:)
+    @project = project
+    @graph = Hashira::Coupling::Graph.new(project, trees, census(trees, packaging))
+  end
+
+  attr_reader :graph
+
+  def findings = RULES.flat_map { it.new(@project, @graph).list }
+
+  private
+
+  def census(trees, packaging) = Hashira::Coupling::Census.new(@project, trees, packaging:)
+end

data/lib/hashira/coupling/roll_call.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+class Hashira::Coupling::RollCall
+  MIN_WORDS = 3
+
+  MIN_FILES = 3
+
+  MIN_PACKAGES = 2
+
+  Roll = Data.define(:words, :files, :packages)
+
+  def initialize(lists, homes)
+    @lists = lists
+    @homes = homes
+  end
+
+  def rolls = maximal(candidates.filter_map { entry(it) }).sort_by(&:words)
+
+  private
+
+  def files = @files ||= @lists.keys.sort
+
+  def candidates
+    files.combination(2).map { |one, two| @lists[one] & @lists[two] }.select { it.size >= MIN_WORDS }.uniq
+  end
+
+  def entry(words)
+    holders = files.select { @lists[it] >= words }
+    spread = holders.map { @homes[it] }.uniq.sort
+    return unless holders.size >= MIN_FILES && spread.size >= MIN_PACKAGES
+    Roll.new(words: words.sort, files: holders, packages: spread)
+  end
+
+  def maximal(rolls)
+    rolls.reject { |roll| swallowed?(roll, rolls) }
+  end
+
+  def swallowed?(roll, rolls) = rolls.any? { swallows?(it, roll) }
+
+  def swallows?(big, small)
+    mine = big.words
+    theirs = small.words
+    mine != theirs && (theirs - mine).empty?
+  end
+end

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,9 +1,10 @@
 # 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)
+    @typed = Set.new
     counted = Set.new
     placed.each { |definition, package| admit(definition, package, counted) }
   end
@@ -12,6 +13,8 @@ class Hashira::Analysis::Roster
 
   def origins = @registry.origins
 
+  def type?(path) = @typed.include?(path)
+
   def packages = @types.keys | @registry.packages
 
   private
@@ -20,6 +23,7 @@ class Hashira::Analysis::Roster
     return unless package
     path = definition.path
     @registry.register(path, package)
+    @typed << path if definition.type?
     @types[package] += 1 if definition.counted? && counted.add?(path)
   end
 end

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,8 @@
 # frozen_string_literal: true
 
-class Hashira::Analysis::Resolver
+class Hashira::Coupling::Scope
+  CORE = Object.constants.select { Object.const_source_location(it) == [] }.to_set(&:to_s).freeze
+
   def initialize(registry, catalog, placement)
     @registry = registry
     @catalog = catalog
@@ -10,7 +12,7 @@ class Hashira::Analysis::Resolver
   def resolve(segments, nesting)
     return if @placement.skip?(segments)
     scoped = nesting.reverse_each.filter_map { descend(it, segments) }.first
-    scoped ? qualify(scoped) : @registry.package(@catalog.strip(segments))
+    scoped ? qualify(scoped) : outward(@catalog.strip(segments))
   end
 
   def pinpoint(segments)
@@ -20,9 +22,11 @@ class Hashira::Analysis::Resolver
 
   private
 
+  def outward(path) = CORE.include?(path.first) ? @registry.rooted(path) : @registry.package(path)
+
   def descend(entry, segments)
     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

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 class Hashira::Duplication::DuplicationFinding
+  KIND = "duplication"
+
   def initialize(cluster, churn)
     @cluster = cluster
     @churn = churn
@@ -8,21 +10,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: KIND, 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