hashira 0.5.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 698031b3fff8e705bf80379be16ee05ecacfa9c137459ab8beb855cee1c624dd
-  data.tar.gz: c50d6bc7ee142f665c8764d56d7fdf07de381b00529715e37682aed6f0f1856d
+  metadata.gz: a0b871ab3e0bf096a2752a48a4c3776d2dbe2ee0cae33b2df8af89649d0952ca
+  data.tar.gz: b1058810a8d965e1010044691d1b11571f21b077581f5e435d40b0d263f133b9
 SHA512:
-  metadata.gz: 4ce8b38adba57e0d1bdf6343362efb3e205c6455d5634bf3cd07c2b429870423268fc4263215ad3ea767284a7acc906901259acbbec7570d386db7fc0759626b
-  data.tar.gz: 3670d8b067f2535d745c3785d52087f2aa189909511566e8452818da408e82882077fe428a72b16470640f60bddcdcbd0fbc6109fc412d64652648c20b1bcb9c
+  metadata.gz: 24d9aae54c58e39a54799efdf9749f501000162c8ea8f9a38e02523fb6ee3122a98daf6591cfaf7816f3a2cd66f20218c08ff27579bc1b58a269e4ce7bddda92
+  data.tar.gz: 158bf3af24e081df3483e3d124833f6943404cfdab6ca1f2f7235115a400cfb1c48f885fb16b290fc529ebc1556c8eb5ed97119f635c9869ae881b44be51c599

data/CHANGELOG.md

@@ -5,6 +5,36 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.6.0] - 2026-08-05
+
+### Changed
+
+- **feature_envy now respects ownership.** The classic remedy — move the
+  method onto the envied object — assumes the envied class is yours to edit.
+  The smell now stays quiet when the method body itself proves otherwise:
+  the name is type-guarded only against constants the analyzed code never
+  defines (`node.is_a?(Prism::CallNode)`); every call on it is a literal-key
+  read (`msg["id"]`, `values_at`, `dig`, `key?` — wire data, not an object);
+  it was built from a literal in the method itself (`options = { ... }`); it
+  was derived by calling a foreign name or foreign constant
+  (`value = node.unescaped`, `app = Rails.application`); it was rescued from
+  a foreign or implied error class (`rescue => e`); the method dispatches on
+  it through a constant table keyed entirely by foreign classes
+  (`TABLE[node.class]`); or the method is a stateless converter whose last
+  act is building a typed object. Guards against types the codebase does
+  define — including by suffix, and including subclasses of gem classes —
+  still flag, as do rescues from error classes the codebase defines and
+  tables keyed by owned classes, so anemic-model envy in Rails apps is
+  untouched.
+
+### Added
+
+- **boundary_sprawl** — the aggregate the suppression above makes room for:
+  when 12+ methods across 3+ files each type-guard against the same foreign
+  root (`Prism`, `ActiveRecord`, ...), one finding proposes fronting that
+  boundary with an adapter. One method inspecting a foreign type is a fact of
+  life; a codebase-wide sprawl of them is a missing seam.
+
 ## [0.5.1] - 2026-08-05
 
 ### Fixed

data/README.md

@@ -294,7 +294,7 @@ it does inside Ruby:
 ## Code smells
 
 RuboCop counts lines and branches inside one method; design smells are about how
-objects treat each other, and no line count sees that. hashira ships the eleven
+objects treat each other, and no line count sees that. hashira ships the twelve
 smells that carry that design signal — the object-relationship kinds, not the
 naming, size, and style checks a linter already argues about — read from the
 same parse trees the other analyzers already built:
@@ -310,7 +310,16 @@ Findings (2):
 What each one catches:
 
 - **feature_envy** — a method refers to another object more than to itself; the
-  behavior probably belongs over there.
+  behavior probably belongs over there. Stays quiet when the method's own body
+  proves the envied thing is foreign — type-guarded (or table-dispatched) only
+  against constants the codebase never defines, read purely through literal
+  keys (`msg["id"]`), built from a literal or derived from a foreign call in
+  the method itself, rescued from a foreign error class, or consumed by a
+  stateless converter that ends by building a typed object — because "move
+  the method" needs a destination you own.
+- **boundary_sprawl** — 12+ methods across 3+ files each type-guard against the
+  same foreign root (`Prism`, `ActiveRecord`, ...). One method inspecting a
+  foreign type is a fact of life; a sprawl of them is a missing adapter.
 - **utility_function** — a public instance method that touches no instance state;
   it isn't really a method of this class. Private stateless helpers are fine, and
   `module_function` modules are exempt — that's what they're for.
@@ -334,7 +343,7 @@ What each one catches:
   cheapest type there is.
 
 Smell findings gate and ratchet like every other kind — `--fail-on smells` covers
-all eleven, or name one (`--fail-on feature_envy`); `--skip smells` drops the
+all twelve, or name one (`--fail-on feature_envy`); `--skip smells` drops the
 analyzer entirely.
 
 ## Hotspots

data/lib/hashira/pipeline.rb

@@ -9,7 +9,9 @@ class Hashira::Pipeline
 
   STRUCTURAL = Hashira::Coupling::Report::RULES.map { it::KIND }.freeze
 
-  SMELLS = Hashira::Smells::Report::CHECKS.map(&:kind).sort.freeze
+  SMELLS = (
+    Hashira::Smells::Report::CHECKS.map(&:kind) + [Hashira::Smells::BoundarySprawl::KIND]
+  ).sort.freeze
 
   def initialize(project, enabled: ANALYZERS, packaging: :auto)
     @project = project

data/lib/hashira/report/smell_phrases.rb

@@ -19,6 +19,12 @@ module Hashira::Report::Phrases
       "Name the result in a local variable."
   end
 
+  def on_boundary_sprawl(finding)
+    detail = finding.detail
+    "#{detail[:count]} methods across #{detail[:files]} files each pick apart #{finding.package}'s " \
+      "internals. Front the boundary with one adapter the rest can lean on."
+  end
+
   def on_feature_envy(finding)
     detail = finding.detail
     names = detail[:names]

data/lib/hashira/smells/boundary_sprawl.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+class Hashira::Smells::BoundarySprawl
+  KIND = "boundary_sprawl"
+
+  METHOD_FLOOR = 12
+
+  FILE_FLOOR = 3
+
+  SHOWN = 4
+
+  def initialize(subjects, ownership)
+    @subjects = subjects
+    @ownership = ownership
+  end
+
+  def findings
+    reaches.filter_map { |root, contexts| finding(root, contexts) }
+  end
+
+  private
+
+  def reaches
+    @subjects.each_with_object({}) do |subject, map|
+      Hashira::Smells::Foreign.new(subject, @ownership).reaches.each { (map[it] ||= []) << subject }
+    end
+  end
+
+  def finding(root, contexts)
+    files = contexts.map(&:file).uniq
+    build(root, contexts, files) if wide?(contexts.size, files.size)
+  end
+
+  def wide?(methods, files) = methods >= METHOD_FLOOR && files >= FILE_FLOOR
+
+  def build(root, contexts, files)
+    Hashira::Analysis::Finding.new(
+      kind: KIND, package: root,
+      detail: { count: contexts.size, files: files.size },
+      evidence: contexts.first(SHOWN).map(&:site)
+    )
+  end
+end

data/lib/hashira/smells/census.rb

@@ -6,8 +6,11 @@ class Hashira::Smells::Census
   def initialize(project, trees)
     @project = project
     @trees = trees
+    @ownership = Hashira::Smells::Ownership.new(trees.values)
   end
 
+  attr_reader :ownership
+
   def types = @trees.flat_map { |path, tree| harvest(@project.relative(path), tree) }
 
   private
@@ -26,7 +29,7 @@ class Hashira::Smells::Census
 
   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:)
+      Hashira::Smells::MethodContext.new(owner: name, node: def_node, file:, section:, ownership: @ownership)
     end
   end
 end

data/lib/hashira/smells/contexts.rb

@@ -32,7 +32,7 @@ module Hashira
     end
 
     MethodContext =
-      Data.define(:owner, :node, :file, :section) do
+      Data.define(:owner, :node, :file, :section, :ownership) do
         def subject = "#{owner}#{singleton? ? "." : "#"}#{node.name}"
 
         def line = node.location.start_line

data/lib/hashira/smells/feature_envy.rb

@@ -9,7 +9,9 @@ class Hashira::Smells::FeatureEnvy < Hashira::Smells::Check
 
   def refs = @refs ||= Hashira::Smells::Refs.new(subject.node)
 
-  def envied = @envied ||= refs.envious
+  def envied = @envied ||= refs.envious.reject { foreign.dismiss?(it) }
+
+  def foreign = @foreign ||= Hashira::Smells::Foreign.new(subject, subject.ownership)
 
   def detail = { site:, names: envied }
 

data/lib/hashira/smells/foreign.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require "prism"
+
+class Hashira::Smells::Foreign
+  TYPE_TESTS = %i[is_a? kind_of? instance_of?].freeze
+
+  KEYED_READS = %i[[] fetch values_at dig key?].freeze
+
+  KEYS = [Prism::StringNode, Prism::SymbolNode].freeze
+
+  LITERALS = [Prism::HashNode, Prism::KeywordHashNode, Prism::ArrayNode, Prism::StringNode].freeze
+
+  STATE = [
+    Prism::InstanceVariableReadNode, Prism::InstanceVariableWriteNode,
+    Prism::InstanceVariableOrWriteNode, Prism::InstanceVariableAndWriteNode,
+    Prism::InstanceVariableOperatorWriteNode, Prism::InstanceVariableTargetNode
+  ].freeze
+
+  def initialize(subject, ownership)
+    node = subject.node
+    @body = Hashira::Smells::Scope.inside(node)
+    @tail = tail(node)
+    @ownership = ownership
+  end
+
+  def dismiss?(name)
+    convert? || fenced?(name) || wire?(name) || built?(name) ||
+      derived?(name) || rescued?(name)
+  end
+
+  def reaches
+    tests { true }.reject { @ownership.owned?(it) }.map(&:first).uniq
+  end
+
+  private
+
+  def convert?
+    @tail.is_a?(Prism::CallNode) && @tail.name == :new &&
+      Hashira::Analysis::Syntax.segments(@tail.receiver).any? && stateless?
+  end
+
+  def stateless? = @body.none? { STATE.include?(it.class) }
+
+  def fenced?(name)
+    tested = tests { it == name }
+    tested.any? && tested.none? { @ownership.owned?(it) }
+  end
+
+  def wire?(name)
+    calls = @body.grep(Prism::CallNode).select { |call| local?(call.receiver) { it == name } }
+    calls.any? && calls.all? { keyed?(it) } && reassignments(name).none?
+  end
+
+  def built?(name)
+    writes(name).any? { LITERALS.include?(it.value.class) }
+  end
+
+  def derived?(name)
+    writes(name).any? { spawned?(it.value) }
+  end
+
+  def rescued?(name)
+    snares(name).any? { alien?(it.exceptions) }
+  end
+
+  def keyed?(call)
+    names = call.arguments&.arguments
+    KEYED_READS.include?(call.name) && names&.any? &&
+      names.all? { KEYS.include?(it.class) }
+  end
+
+  def writes(name) = among(Prism::LocalVariableWriteNode, name)
+
+  def reassignments(name) = among(Prism::LocalVariableOperatorWriteNode, name)
+
+  def among(kind, name)
+    @body.grep(kind).select { it.name == name }
+  end
+
+  def snares(name)
+    @body.grep(Prism::RescueNode).select { it.reference&.name == name }
+  end
+
+  def alien?(exceptions)
+    exceptions.map { Hashira::Analysis::Syntax.segments(it) }.none? { @ownership.owned?(it) }
+  end
+
+  def spawned?(value)
+    value.is_a?(Prism::CallNode) && stranger?(value.receiver)
+  end
+
+  def stranger?(node)
+    case node
+    when Prism::LocalVariableReadNode then fenced?(node.name)
+    when Prism::ConstantReadNode, Prism::ConstantPathNode then unowned?(node)
+    else false
+    end
+  end
+
+  def unowned?(node)
+    !@ownership.owned?(Hashira::Analysis::Syntax.segments(node))
+  end
+
+  def tests(&)
+    (probes(&) + arms(&)).map { Hashira::Analysis::Syntax.segments(it) }.reject(&:empty?) + lookups(&)
+  end
+
+  def probes(&)
+    @body.grep(Prism::CallNode).select { TYPE_TESTS.include?(it.name) && local?(it.receiver, &) }.filter_map { key(it) }
+  end
+
+  def arms(&)
+    @body.grep(Prism::CaseNode).select { local?(it.predicate, &) }.flat_map(&:conditions).flat_map(&:conditions)
+  end
+
+  def lookups(&)
+    @body.grep(Prism::CallNode).select { it.name == :[] && sorts?(key(it), &) }.flat_map { @ownership.keys(Hashira::Analysis::Syntax.segments(it.receiver)) }
+  end
+
+  def sorts?(argument, &)
+    argument.is_a?(Prism::CallNode) && argument.name == :class &&
+      local?(argument.receiver, &)
+  end
+
+  def local?(node, &) = node.is_a?(Prism::LocalVariableReadNode) && yield(node.name)
+
+  def key(call) = call.arguments&.arguments&.first
+
+  def tail(def_node) = Hashira::Analysis::Syntax.statements(def_node).compact.last
+end

data/lib/hashira/smells/ownership.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+class Hashira::Smells::Ownership
+  def initialize(trees)
+    @suffixes = Set.new
+    @tables = {}
+    trees.each { survey(it) }
+  end
+
+  def owned?(segments) = @suffixes.include?(segments.join("::"))
+
+  def keys(segments) = @tables.fetch(segments.join("::"), [])
+
+  private
+
+  def survey(tree)
+    Hashira::Analysis::TypeWalk.each(tree) do |node, full|
+      absorb(full)
+      Hashira::Analysis::Syntax.constants(node).each { record(full, it) }
+    end
+  end
+
+  def record(full, constant)
+    path = full + [constant.name.to_s]
+    absorb(path)
+    chart(path, thaw(constant.value))
+  end
+
+  def absorb(path)
+    @suffixes.merge(suffixes(path))
+  end
+
+  def chart(path, value)
+    return unless value.is_a?(Prism::HashNode)
+    keys = value.elements.map { spine(it) }
+    return if keys.empty? || keys.any?(&:nil?)
+    suffixes(path).each { @tables[it] = keys }
+  end
+
+  def thaw(value)
+    frozen?(value) ? value.receiver : value
+  end
+
+  def frozen?(value) = value.is_a?(Prism::CallNode) && value.name == :freeze
+
+  def spine(element)
+    return unless element.is_a?(Prism::AssocNode)
+    segments = Hashira::Analysis::Syntax.segments(element.key)
+    segments unless segments.empty?
+  end
+
+  def suffixes(path)
+    path.each_index.map { path.drop(it).join("::") }
+  end
+end

data/lib/hashira/smells/report.rb

@@ -1,14 +1,17 @@
 # frozen_string_literal: true
 
+require_relative "boundary_sprawl"
 require_relative "check"
 require_relative "control_parameter"
 require_relative "data_clump"
 require_relative "duplicate_method_call"
 require_relative "feature_envy"
+require_relative "foreign"
 require_relative "instance_variable_assumption"
 require_relative "manual_dispatch"
 require_relative "module_initialize"
 require_relative "nil_check"
+require_relative "ownership"
 require_relative "repeated_conditional"
 require_relative "too_many_instance_variables"
 require_relative "utility_function"
@@ -21,13 +24,18 @@ class Hashira::Smells::Report
   PROBES = CHECKS.reject(&:judge?).freeze
 
   def initialize(project, trees)
-    @types = Hashira::Smells::Census.new(project, trees).types
+    @census = Hashira::Smells::Census.new(project, trees)
+    @types = @census.types
   end
 
-  def findings = @findings ||= sniff(@types, JUDGES) + sniff(@types.flat_map(&:defs), PROBES)
+  def findings = @findings ||= sniff(@types, JUDGES) + sniff(methods, PROBES) + sprawl
 
   private
 
+  def methods = @types.flat_map(&:defs)
+
+  def sprawl = Hashira::Smells::BoundarySprawl.new(methods, @census.ownership).findings
+
   def sniff(subjects, checks) = subjects.flat_map { |subject| verdicts(subject, checks) }
 
   def verdicts(subject, checks) = checks.filter_map { |check| check.new(subject).finding }

data/lib/hashira/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Hashira
-  VERSION = "0.5.1"
+  VERSION = "0.6.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hashira
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.6.0
 platform: ruby
 authors:
 - Giacomo GK
@@ -10,10 +10,10 @@ cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 description: Measures package coupling (Ca/Ce/instability, SDP violations, cycles),
-  per-method cognitive complexity, and near-miss code duplication in a Ruby codebase
-  from the AST, then ranks files by cost against git churn. Findings are backed by
-  file-level evidence, and a baseline ratchets edges and findings for CI — direction,
-  not a score.
+  per-method cognitive complexity, near-miss code duplication, and twelve design smells
+  in a Ruby codebase from the AST, then ranks files by cost against git churn. Findings
+  are backed by file-level evidence, and a baseline ratchets edges and findings for
+  CI — direction, not a score.
 email:
 - giaco@hey.com
 executables:
@@ -126,6 +126,7 @@ files:
 - lib/hashira/report/smell_phrases.rb
 - lib/hashira/report/text.rb
 - lib/hashira/report/view.rb
+- lib/hashira/smells/boundary_sprawl.rb
 - lib/hashira/smells/census.rb
 - lib/hashira/smells/check.rb
 - lib/hashira/smells/conditions.rb
@@ -134,10 +135,12 @@ files:
 - lib/hashira/smells/data_clump.rb
 - lib/hashira/smells/duplicate_method_call.rb
 - lib/hashira/smells/feature_envy.rb
+- lib/hashira/smells/foreign.rb
 - lib/hashira/smells/instance_variable_assumption.rb
 - lib/hashira/smells/manual_dispatch.rb
 - lib/hashira/smells/module_initialize.rb
 - lib/hashira/smells/nil_check.rb
+- lib/hashira/smells/ownership.rb
 - lib/hashira/smells/param_check.rb
 - lib/hashira/smells/refs.rb
 - lib/hashira/smells/repeated_conditional.rb
@@ -171,5 +174,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.17
 specification_version: 4
-summary: Coupling, cognitive-complexity, and duplication metrics for Ruby, via Prism
+summary: Coupling, cognitive-complexity, duplication and code-smell metrics for Ruby,
+  via Prism
 test_files: []