hashira 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2e10a9ee1cb16f2b8090dfe962aaa9b8c0fc7b2bf598f507c31817cc6a4a334b
-  data.tar.gz: 88e97bb9d5a8b524928014aa2248c917dff0fa3d9a19e785cc2477a40341204c
+  metadata.gz: 574b35721d888046d7d8bbe02129896ebb6305aca89c30127c5372cb855bff74
+  data.tar.gz: ecd9eae0bf5a0cb5baf9b7637401ce0e12afdebcaa7e61e1c3f58b155e16a7bc
 SHA512:
-  metadata.gz: 332e29ec2e0841e9ee3476e9155d707b00b97ec116fd88a578bd3b38d4aa2f169cb2cd1dcb531fb9e22ba6909893559463f0282f151b0815f76729efd4e913fb
-  data.tar.gz: 2ab5337504ff4390112874e55cc661970b94d3638b79ad93900d0d2c642eaa2cdcfdd9e9acd21eb80bca0e5371585fa7a1ea0a6e7ed8512df60dfbc087b397cd
+  metadata.gz: 5b08c0cb5f567948aa66f6e1e69d5c610b4eeb75811940b7d833e3c08d279372d5d27100c1efa3f0b3917e0f9fbd32d675e7284039e57086044c8e26e7edb509
+  data.tar.gz: 10a1128b98b097b168adbaca6b2c0408a712d992725f5c41d1146fcc43cf975511cbc9dd4dd31a3bc3bfc42b2279906859233f66cde4eada83d96f20f3449aae

data/CHANGELOG.md

@@ -5,10 +5,67 @@ 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.5.0] - 2026-08-04
+
+### Added
+
+- `wide_edge` coupling finding: an edge carrying five or more distinct
+  constants is an interface with that many reasons to change — front the
+  target with one facade. Found from the same constant-level usage data as
+  `mixed_audience`. Its first run flagged the pipeline's own five-constant
+  reach into `coupling`, dissolved by the new `Coupling::Report` facade.
+- `roll_call` coupling finding: a list of three or more words (symbols or
+  string keys in array and hash literals) maintained by hand in three or more
+  files across two or more packages is a registry in disguise. Its first run
+  flagged the analyzer names synced between the pipeline, `--fail-on`, and the
+  JSON report — dissolved by deriving `--fail-on` kinds from
+  `Pipeline::ANALYZERS` and the coupling rule roster.
+- `Hashira/ProsePlacement` cop: sentence-length string literals are presentation
+  and belong under `report/` or `ci/` — domain classes pass data. All finding
+  messages now render in `Report::Phrases` from structured `Finding#detail`;
+  `Finding` no longer carries a `message` member (the JSON report still emits
+  a phrased `message` per finding).
+- Coverage floors raised to 100% line and 100% branch — and CI now gates
+  `wide_edge` and `roll_call` alongside cycles, SDP, and mixed audiences.
+
+- `mixed_audience` coupling finding: a package whose constants split into
+  parts with disjoint client bases — one set of packages leaning on one slice,
+  another set on another — is separate packages in disguise. Detected from
+  constant-level inbound references: clients whose touched constants overlap
+  merge into one audience; constants used by a strict majority of clients are
+  set aside as the shared base layer; two or more remaining parts of at least
+  two constants each name the seam. Gate with `--fail-on mixed_audience`.
+  Hashira's first run on itself flagged its own oldest namespace, `analysis` —
+  and the split below dissolved it.
+
+### Changed
+
+- **Breaking:** the coupling machinery moved out of `Hashira::Analysis` into
+  `Hashira::Coupling` (`Graph`, `Census`, `Cycles`, the structural findings,
+  packaging and resolution), matching the `--skip coupling` analyzer name.
+  `Hashira::Analysis` now holds only the substrate every analyzer shares:
+  `Syntax`, `NodeWalk`, `TypeWalk`, and `Finding`. Exactly the seam the new
+  `mixed_audience` finding pointed at; hashira now gates itself with
+  `--fail-on cycles,sdp,mixed_audience` and an empty-findings baseline.
+
 ## [0.4.0] - 2026-08-02
 
 ### Added
 
+- Code smells analyzer: eleven design smells — the object-relationship kinds
+  no line count sees —
+  `control_parameter`, `data_clump`, `duplicate_method_call`, `feature_envy`,
+  `instance_variable_assumption`, `manual_dispatch`, `module_initialize`,
+  `nil_check`, `repeated_conditional`, `too_many_instance_variables`, and
+  `utility_function` — reported as findings with file:line evidence, gated and
+  ratcheted like every other kind. On by default; `--skip smells` drops the
+  analyzer; `--fail-on smells` gates all eleven, or name a single kind
+  (`--fail-on feature_envy`). `@x ||=` memoization counts neither as class
+  state nor as an ivar assumption, `module_function` methods are exempt, and
+  `utility_function` flags public instance methods only. Methods born inside
+  blocks or `class << self` are seen like any other, and safe navigation
+  counts wherever a plain call would.
+
 - Rails awareness. A directory with `config/application.rb` inside it (the
   Rails root) or beside it (its `app` folder) is detected as a Rails app:
   coupling defaults to namespace packaging, and under namespace packaging
@@ -209,6 +266,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Output formats: text, JSON, Graphviz dot, Mermaid (`--format`, `--json`).
 - `--help` and `--version`.
 
+[0.5.0]: https://github.com/giacope/hashira/releases/tag/v0.5.0
 [0.4.0]: https://github.com/giacope/hashira/releases/tag/v0.4.0
 [0.3.0]: https://github.com/giacope/hashira/releases/tag/v0.3.0
 [0.2.0]: https://github.com/giacope/hashira/releases/tag/v0.2.0

data/README.md

@@ -1,17 +1,17 @@
 # hashira
 
-🏛️ **Coupling, cognitive-complexity and duplication metrics for Ruby, read straight from the AST via [Prism](https://github.com/ruby/prism).**
+🏛️ **Coupling, cognitive-complexity, duplication and code-smell metrics for Ruby, read straight from the AST via [Prism](https://github.com/ruby/prism).**
 
-hashira tells you which file to open first. It reads a Ruby codebase three ways —
-which packages depend on which, how hard each method is to follow, and what has been
-copy-pasted — then ranks every file by what it costs you against how often you
-actually change it. Every finding names the file and line behind it, and a committed
+hashira tells you which file to open first. It reads a Ruby codebase four ways —
+which packages depend on which, how hard each method is to follow, what has been
+copy-pasted, and which objects handle each other's data — then ranks every file by
+what it costs you against how often you actually change it. Every finding names the file and line behind it, and a committed
 baseline ratchets the whole set in CI, so the build fails on what *this commit* made
 worse rather than on a score nobody agrees on.
 
 - **Zero runtime dependencies.** Prism ships with Ruby 3.4+; nothing else to install.
 - **Reads the AST, never strings.** Every signal comes from the parse tree. Comments and string literals are invisible.
-- **Three analyzers, opt-out.** Coupling, complexity, and duplication run together by default; `--skip` drops any.
+- **Four analyzers, opt-out.** Coupling, complexity, duplication, and smells run together by default; `--skip` drops any.
 - **Ranked, not graded.** The hotspot rollup orders files by cost × churn — a work queue, not a letter that reads the same on every healthy repo.
 - **Findings, not just a dashboard.** Cycles, SDP violations, complexity hotspots, and clone clusters — each backed by file-level evidence and a plain-language fix.
 - **Made for CI.** Ratchet edges *and* findings against a baseline, so no clean slate is required. Or gate outright with `--fail-on`.
@@ -39,7 +39,7 @@ A healthy project reports `Findings (0): none ✓ — structure is healthy`.
 
 ## Contents
 
-[Install](#install) · [Getting started](#getting-started) · [Coupling: how to read the numbers](#coupling-how-to-read-the-numbers) · [Rails apps](#rails-apps) · [Cognitive complexity](#cognitive-complexity) · [Duplication](#duplication) · [Hotspots](#hotspots) · [How it works](#how-it-works) · [CI](#ci) · [Other formats](#other-formats) · [Why cognitive complexity](#why-cognitive-complexity) · [Why no A, D, or zones](#why-no-a-d-or-zones)
+[Install](#install) · [Getting started](#getting-started) · [Coupling: how to read the numbers](#coupling-how-to-read-the-numbers) · [Rails apps](#rails-apps) · [Cognitive complexity](#cognitive-complexity) · [Duplication](#duplication) · [Code smells](#code-smells) · [Hotspots](#hotspots) · [How it works](#how-it-works) · [CI](#ci) · [Other formats](#other-formats) · [Why cognitive complexity](#why-cognitive-complexity) · [Why no A, D, or zones](#why-no-a-d-or-zones)
 
 ## Install
 
@@ -83,25 +83,28 @@ hashira's own source:
 
 ```console
 $ hashira
-Package (layer) metrics for lib/hashira  (9 packages, 75 files)
+Package (layer) metrics for lib/hashira  (11 packages, 111 files)
 
 package       TC  Ca  Ce     I  Cyc
 ----------------------------------------
-analysis      14   3   0  0.00  -
+analysis       3   4   0  0.00  -
 diagram        3   1   0  0.00  -
 hotspots       1   1   0  0.00  -
 duplication   14   2   1  0.33  -
 report         8   2   1  0.33  -
+ci             8   1   1  0.50  -
 complexity     7   1   1  0.50  -
-(root)         3   2   4  0.67  -
-ci             8   1   2  0.67  -
-cli            6   0   4  1.00  -
+coupling      24   1   1  0.50  -
+smells        21   1   1  0.50  -
+(root)         4   1   5  0.83  -
+cli            8   0   4  1.00  -
 
 Legend: TC total types, Ca afferent (incoming), Ce efferent (outgoing),
         I=Ce/(Ce+Ca) instability (0=maximally stable, 1=maximally unstable)
 
 Dependencies (DependsUpon(refs) -> | <- UsedBy):
-  (root)       -> analysis(4), complexity(1), duplication(1), hotspots(1) <- ci, cli
+  (root)       -> complexity(1), coupling(5), duplication(1), hotspots(1), smells(1) <- cli
+  analysis     -> (none)                           <- complexity, coupling, duplication, smells
   duplication  -> analysis(3)                      <- (root), report
   ...
 
@@ -109,27 +112,27 @@ Cognitive complexity — worst methods (Cog = how hard to read, Calls = message
 
 method                                        Cog  Calls  Loc
 -------------------------------------------------------------
-Hashira::Report::Text#print                     3      7  report/text.rb:11
-Hashira::Analysis::CycleSearch#cycle?           3      3  analysis/cycle_search.rb:19
-Hashira::CLI::CommandLine#usage_options         3      5  cli/command_line.rb:20
-Hashira::Duplication::Delta#kind                3      6  duplication/delta.rb:21
+Hashira::Coupling::NamespacePrefix#wrapper      4      8  coupling/namespace_prefix.rb:19
+Hashira::Analysis::Syntax#anchor                4     12  analysis/syntax.rb:26
+Hashira::Smells::Conditions#branches            4     10  smells/conditions.rb:23
+Hashira::Coupling::Roster#admit                 3      4  coupling/roster.rb:19
 ...
 
 Per-class rollup (Cog total survives extract-method; Peak is the worst method it hides):
 
 class                              Cog  Methods   Peak
 ------------------------------------------------------
-Hashira::CLI::CommandLine           16       15      3
-Hashira::Analysis::CycleSearch       8        5      3
+Hashira::Project                    12       15      3
+Hashira::CLI::CommandLine           12       15      3
 ...
 
 Hotspots — cost × churn (where refactoring pays the most):
 
 file                                             Cog   Dup  Churn    Rank
 -------------------------------------------------------------------------
-cli/run.rb                                         1    36      2      74
-cli/command_line.rb                               16     0      3      48
-pipeline.rb                                        7     0      3      21
+pipeline.rb                                       10     0      6      60
+cli/command_line.rb                               12     0      4      48
+project.rb                                        12     0      4      48
 ...
 
 Findings (0):
@@ -154,6 +157,18 @@ domain layer near 0.00. The findings are about arrows pointing the wrong way:
   Stable Dependencies Principle ("depend in the direction of stability"), one of
   Robert C. Martin's [package principles](https://en.wikipedia.org/wiki/Package_principles).
 - **Cycle** — packages depending on each other in a loop.
+- **Mixed audience** — the constants of one package split into parts with
+  separate client bases: one set of packages leans on one slice, another set on
+  a disjoint slice. Each part is a separate package in disguise; the finding
+  names the seam, and — when most clients also share a few constants — the
+  shared base layer to extract. Composition roots blur the picture only if they
+  touch a constant some other client also touches, which facades avoid.
+- **Wide edge** — one package reaches into another through five or more
+  distinct constants. Every constant on the edge is a reason for the client to
+  change; a facade narrows the interface to one.
+- **Roll call** — the same list of three or more words (symbols, string keys)
+  is maintained by hand in three or more files across packages. The list wants
+  to be data with a single owner — a registry the other sites derive from.
 
 Each finding comes with file-level evidence; for cycles, the shortest cycle
 path and its lightest edge. What a finding means for your design is your call.
@@ -277,10 +292,56 @@ it does inside Ruby:
   are called out — that's where one copy gets fixed and the other silently
   drifts. Silent when git isn't there; no configuration either way.
 
+## 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
+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:
+
+```console
+Findings (2):
+  feature_envy: Cart#price refers to 'item' more than to self (cart.rb:12). The behavior may belong on item.
+      · item (lines 13, 14)
+  control_parameter: Report#write is steered by 'quoted' (report.rb:31). Split the method, or pass a strategy instead of a flag.
+      · quoted (line 32)
+```
+
+What each one catches:
+
+- **feature_envy** — a method refers to another object more than to itself; the
+  behavior probably belongs over there.
+- **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.
+- **control_parameter** — an argument used only to pick an execution path; the
+  caller already knew which branch it wanted.
+- **data_clump** — the same two-plus parameters travel through three or more
+  methods; a value object is missing.
+- **duplicate_method_call** — the identical receiver-and-arguments call repeated
+  inside one method; name the result once.
+- **repeated_conditional** — one class testing the same condition in three or
+  more places; polymorphism is overdue.
+- **too_many_instance_variables** — more than four per class. Memoization
+  (`@x ||=`) doesn't count as state.
+- **instance_variable_assumption** — an ivar read that no `initialize` ever
+  assigns; the reader is assuming another method ran first.
+- **manual_dispatch** — `respond_to?` then send: a type check wearing a duck
+  costume.
+- **module_initialize** — `initialize` in a mixin; construction order becomes
+  anyone's guess.
+- **nil_check** — `nil?`, `== nil`, `when nil`: simulated polymorphism on the
+  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
+analyzer entirely.
+
 ## Hotspots
 
-The three analyzers each answer a different question. The rollup joins them per
-file and adds the one signal that isn't in the AST — how often the file actually
+Each analyzer answers a different question. The hotspot rollup joins the cost
+signals — complexity and duplication — per file and adds the one signal that isn't in the AST — how often the file actually
 changes — because cost you never pay isn't worth paying down:
 
 ```console
@@ -340,7 +401,7 @@ it. Git is asked once, lazily, and only if something needs churn.
 at all. It only works on a codebase that starts clean.
 
 ```sh
-hashira --fail-on cycles,sdp,complexity,duplication   # any subset, comma-separated
+hashira --fail-on cycles,sdp,mixed_audience,wide_edge,roll_call,smells   # any subset
 ```
 
 The ratchet is the one you can adopt today. Commit a baseline of what's true now

data/lib/hashira/analysis/finding.rb

@@ -3,8 +3,8 @@
 module Hashira
   module Analysis
     Finding =
-      Data.define(:kind, :package, :message, :evidence, :cycle, :digest) do
-        def initialize(cycle: nil, digest: nil, **rest) = super
+      Data.define(:kind, :package, :detail, :evidence, :cycle, :digest) do
+        def initialize(cycle: nil, digest: nil, detail: nil, **rest) = super
 
         def signature = "#{kind}:#{identity}"
 

data/lib/hashira/ci/ratchet.rb

@@ -14,21 +14,17 @@ class Hashira::CI::Ratchet
     0
   end
 
-  def check
-    raise(Hashira::Error, "no baseline at #{@baseline.path} — run --update-baseline first") unless @baseline.exist?
-    vet
-    Hashira::CI::RatchetReport.new(@graph, @findings, io: @io).print(drift, delta)
+  def check = Hashira::CI::RatchetReport.new(@graph, @findings, io: @io).print(drift, delta)
+
+  def blocker
+    return "no baseline at #{@baseline.path} — run --update-baseline first" unless @baseline.exist?
+    mismatch unless @baseline.packaging == packaging
   end
 
   private
 
   def packaging = @graph.packaging.to_s
 
-  def vet
-    return if @baseline.packaging == packaging
-    raise(Hashira::Error, mismatch)
-  end
-
   def mismatch
     recorded = @baseline.packaging
     "baseline #{@baseline.path} was recorded with --package-by #{recorded}, but this run " \

data/lib/hashira/cli/fail_on.rb

@@ -1,18 +1,28 @@
 # frozen_string_literal: true
 
+require_relative "../pipeline"
+
 module Hashira::CLI::FailOn
+  SMELLS = %w[
+    control_parameter data_clump duplicate_method_call feature_envy instance_variable_assumption
+    manual_dispatch module_initialize nil_check repeated_conditional too_many_instance_variables
+    utility_function
+  ].freeze
+
+  MEASURES = (Hashira::Pipeline::ANALYZERS - %i[coupling smells]).map(&:to_s).freeze
+
   KINDS = {
-    "cycles" => "cycle", "cycle" => "cycle",
-    "sdp" => "sdp_violation", "sdp_violation" => "sdp_violation",
-    "complexity" => "complexity",
-    "duplication" => "duplication", "dupe" => "duplication"
+    "cycles" => "cycle", "sdp" => "sdp_violation", "dupe" => "duplication",
+    **Hashira::Pipeline::STRUCTURAL.to_h { [it, it] },
+    **MEASURES.to_h { [it, it] },
+    "smells" => SMELLS, **SMELLS.to_h { [it, it] }
   }.freeze
 
   module_function
 
   def parse(list)
     return [] unless list
-    list.split(",").map { kind(it.strip) }.uniq
+    list.split(",").flat_map { Array(kind(it.strip)) }.uniq
   end
 
   def kind(name)

data/lib/hashira/cli/run.rb

@@ -18,11 +18,15 @@ class Hashira::CLI::Run
 
   def update = ratchet.update
 
-  def check = ratchet.check
+  def check
+    stop = ratchet.blocker
+    raise(Hashira::Error, stop) if stop
+    ratchet.check
+  end
 
   def guard = gate.check
 
-  def diagram = renderer.display
+  def diagram = source.print
 
   def json = report(Hashira::Report::Json)
 
@@ -30,11 +34,11 @@ class Hashira::CLI::Run
 
   def report(kind) = kind.new(view).print
 
-  def ratchet = Hashira::CI::Ratchet.new(graph, findings.all, @options.baseline)
+  def ratchet = @ratchet ||= Hashira::CI::Ratchet.new(graph, findings.all, @options.baseline)
 
   def gate = Hashira::CI::Gate.new(findings, @options.fail_on)
 
-  def renderer = Hashira::Diagram::Renderer.new(graph, @options.mode)
+  def source = Hashira::Diagram::Source.new(graph, @options.mode)
 
   def view
     Hashira::Report::View.new(

data/lib/hashira/cli/usage.rb

@@ -4,16 +4,19 @@ module Hashira::CLI::Usage
   TEXT = <<~HELP
     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
+                           kinds: cycles, sdp, mixed_audience, wide_edge,
+                           roll_call, complexity, duplication, smells (all
+                           of them), or one smell kind such as feature_envy
+      --skip ANALYZERS     drop an analyzer; comma-separated: coupling,
+                           complexity, duplication, smells
       --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

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,18 @@
 # 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
-
   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: "complexity", 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 +24,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