hashira 0.4.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2e10a9ee1cb16f2b8090dfe962aaa9b8c0fc7b2bf598f507c31817cc6a4a334b
-  data.tar.gz: 88e97bb9d5a8b524928014aa2248c917dff0fa3d9a19e785cc2477a40341204c
+  metadata.gz: 698031b3fff8e705bf80379be16ee05ecacfa9c137459ab8beb855cee1c624dd
+  data.tar.gz: c50d6bc7ee142f665c8764d56d7fdf07de381b00529715e37682aed6f0f1856d
 SHA512:
-  metadata.gz: 332e29ec2e0841e9ee3476e9155d707b00b97ec116fd88a578bd3b38d4aa2f169cb2cd1dcb531fb9e22ba6909893559463f0282f151b0815f76729efd4e913fb
-  data.tar.gz: 2ab5337504ff4390112874e55cc661970b94d3638b79ad93900d0d2c642eaa2cdcfdd9e9acd21eb80bca0e5371585fa7a1ea0a6e7ed8512df60dfbc087b397cd
+  metadata.gz: 4ce8b38adba57e0d1bdf6343362efb3e205c6455d5634bf3cd07c2b429870423268fc4263215ad3ea767284a7acc906901259acbbec7570d386db7fc0759626b
+  data.tar.gz: 3670d8b067f2535d745c3785d52087f2aa189909511566e8452818da408e82882077fe428a72b16470640f60bddcdcbd0fbc6109fc412d64652648c20b1bcb9c

data/CHANGELOG.md

@@ -5,10 +5,94 @@ 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.1] - 2026-08-05
+
+### Fixed
+
+- The churn scan passes `--no-renames` to `git log`, counting a move as a
+  delete plus an add. Rename detection needs blob contents, so on a partial
+  clone (`--filter=blob:none`) the old command lazy-fetched objects from the
+  network one at a time — on a long history the scan stalled for minutes and
+  looked like a hang. It also made the tally depend on which blobs git could
+  see, so the same tree could report different churn (and different
+  findings) run to run. A dogfood run against a large open-source app fell
+  from 3m39s to under 9 seconds.
+- A bare reference to a Ruby core constant (`String`, `Regexp`, `File`, …)
+  no longer couples to whichever package defines a namespaced namesake such
+  as `Sql::Nodes::Regexp` — Ruby would resolve it to the core class, so
+  hashira now drops the edge. The registry answers these through `rooted`,
+  which skips the shorthand tails: a lexical namesake still shadows the core
+  name as Ruby's own lookup does, and a project that reopens the class at
+  top level still owns it. Dogfooding against a large open-source library,
+  this deleted a phantom `mixed_audience` finding built entirely on `Array`,
+  `String`, and `File`.
+- Constants assigned in a class body (`Node = Struct.new(:path)`) now join the
+  census as definitions, so a bare reference resolves to the local constant
+  instead of a foreign package's namesake — a karat run had minted two phantom
+  edges this way. For usage counts they still collapse into their enclosing
+  type: `wide_edge` measures classes, not the constants they carry.
+
+## [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 +293,8 @@ 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.1]: https://github.com/giacope/hashira/releases/tag/v0.5.1
+[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`.
@@ -26,11 +26,10 @@ package       TC  Ca  Ce     I  Cyc
 billing        1   1   1  0.50  YES
 shipping       1   1   1  0.50  YES
 
-Findings (2):
-  cycle: billing can reach itself: billing -> shipping -> billing — any change
-  may ripple back around. The lightest edge on this cycle is billing -> shipping (1 ref).
-      · billing/client.rb:3: Shipping::Rate
-      · shipping/rate.rb:3: Billing::Client
+Findings (1):
+  cycle: billing can reach itself: billing -> shipping -> billing — any change may ripple back around. The lightest edge on this cycle is billing -> shipping (1 ref).
+      · billing/client.rb:5: Shipping::Rate
+      · shipping/rate.rb:8: Billing::Client
 ```
 
 A healthy project reports `Findings (0): none ✓ — structure is healthy`.
@@ -39,7 +38,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 +82,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 +111,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 +156,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 +291,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 +400,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/analysis/syntax.rb

@@ -33,9 +33,13 @@ module Hashira
         roots.include?(segments.first(1)) ? segments : (stack.last || []) + segments
       end
 
-      def direct(type_node)
+      def direct(type_node) = statements(type_node).grep(Prism::DefNode)
+
+      def constants(type_node) = statements(type_node).grep(Prism::ConstantWriteNode)
+
+      def statements(type_node)
         body = type_node.body
-        (body.is_a?(Prism::StatementsNode) ? body.body : [body]).grep(Prism::DefNode)
+        body.is_a?(Prism::StatementsNode) ? body.body : [body]
       end
     end
   end

data/lib/hashira/churn.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 class Hashira::Churn
-  LOG = "git log --name-only --format= 2>/dev/null"
+  LOG = "git log --no-renames --name-only --format= 2>/dev/null"
   SITES_THAT_DRIFT_APART = 2
 
   def self.scan = new(tally(`#{LOG}`))

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/command_line.rb

@@ -1,47 +1,30 @@
 # frozen_string_literal: true
 
 class Hashira::CLI::CommandLine
-  DEFAULT_BASELINE = "hashira_baseline.json"
-
-  FORMATS = %w[text json dot mermaid].freeze
-
-  CI_FLAGS = { "--update-baseline" => :update, "--ratchet" => :ratchet }.freeze
-
   def initialize(argv)
     @arguments = Hashira::CLI::Arguments.new(argv)
   end
 
-  def options = shortcuts || parsed
+  def options = page || parsed
 
   private
 
-  def shortcuts
-    return usage(:help) if delete("--help") || delete("-h")
-    usage(:version) if delete("--version")
+  def page
+    flag = Hashira::CLI::FLAGS.select(&:page?).find { seen?(it) }
+    Hashira::CLI::Options.page(flag.mode) if flag
   end
 
-  def usage(mode)
-    Hashira::CLI::Options.new(directories: [], mode:, baseline: nil, fail_on: [], skip: [], packaging: :auto)
-  end
+  def seen?(flag) = flag.names.any? { @arguments.delete(it) }
 
   def parsed
-    values = flags
-    values[:mode] = mode(values[:fail_on])
-    Hashira::CLI::Options.new(directories: @arguments.rest, **values)
+    parses = Hashira::CLI::FLAGS.reject(&:page?).to_h { [it, it.read(@arguments)] }
+    Hashira::CLI::Options.new(directories: @arguments.rest, mode: mode(parses), **fields(parses))
   end
 
-  def flags
-    {
-      skip: Hashira::CLI::Skip.parse(take("--skip", "")),
-      fail_on: Hashira::CLI::FailOn.parse(take("--fail-on", "")),
-      baseline: take("--baseline", DEFAULT_BASELINE), packaging: grouping
-    }
-  end
-
-  def grouping = Hashira::CLI::PackageBy.parse(take("--package-by", ""))
+  def fields(parses) = parses.to_h { |flag, value| [flag.field, value] }.except(nil)
 
-  def mode(fail_on)
-    case (asked = requested(fail_on).uniq(&:last))
+  def mode(parses)
+    case (asked = parses.filter_map { |flag, value| flag.bid(value) }.uniq(&:last))
     in [] then :text
     in [[_flag, mode]] then mode
     else conflict(asked)
@@ -51,26 +34,4 @@ class Hashira::CLI::CommandLine
   def conflict(asked)
     raise(Hashira::Error, "conflicting options: #{asked.map(&:first).join(" and ")}")
   end
-
-  def requested(fail_on)
-    CI_FLAGS.filter_map { |flag, mode| [flag, mode] if delete(flag) } + gate(fail_on) + formats
-  end
-
-  def gate(fail_on) = fail_on.empty? ? [] : [["--fail-on", :fail_on]]
-
-  def formats
-    chosen = format
-    modes = chosen.empty? ? [] : [["--format #{chosen}", chosen.to_sym]]
-    delete("--json") ? modes + [["--json", :json]] : modes
-  end
-
-  def format
-    wanted = take("--format", "")
-    return wanted if wanted.empty? || FORMATS.include?(wanted)
-    raise(Hashira::Error.unknown("--format", wanted, FORMATS))
-  end
-
-  def take(flag, default) = @arguments.take(flag, default)
-
-  def delete(flag) = @arguments.delete(flag)
 end

data/lib/hashira/cli/fail_on.rb

@@ -1,18 +1,22 @@
 # frozen_string_literal: true
 
+require_relative "../pipeline"
+
 module Hashira::CLI::FailOn
+  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" => Hashira::Pipeline::SMELLS, **Hashira::Pipeline::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/flag.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+class Hashira::CLI
+  Flag =
+    Data.define(:name, :arg, :default, :field, :parse, :mode, :text) do
+      def initialize(**attributes) = super(arg: nil, default: "", field: nil, parse: nil, mode: nil, **attributes)
+
+      def read(arguments) = arg ? take(arguments) : arguments.delete(name)
+
+      def take(arguments)
+        raw = arguments.take(name, default)
+        parse ? parse.parse(raw) : raw
+      end
+
+      def bid(value)
+        case [mode, value]
+        in [nil, _] | [_, nil] | [_, []] then nil
+        in [:parsed, chosen] then ["#{name} #{chosen}", chosen]
+        else [name, mode]
+        end
+      end
+
+      def label = [name, arg].compact.join(" ")
+
+      def names = name.split(", ")
+
+      def page? = Hashira::CLI::Usage::PAGES.include?(mode)
+    end
+end

data/lib/hashira/cli/flags.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "fail_on"
+require_relative "flag"
+require_relative "format"
+require_relative "package_by"
+require_relative "skip"
+
+class Hashira::CLI
+  FLAGS = [
+    Flag.new(
+      name: "--format", arg: "FORMAT", parse: Format, mode: :parsed,
+      text: ["text (default), json, dot, or mermaid"]
+    ),
+    Flag.new(name: "--json", mode: :json, text: ["shorthand for --format json"]),
+    Flag.new(
+      name: "--fail-on", arg: "KINDS", field: :fail_on, parse: FailOn, mode: :fail_on,
+      text: [
+        "exit 1 if findings exist; comma-separated",
+        "kinds: cycles, sdp, mixed_audience, wide_edge,",
+        "roll_call, complexity, duplication, smells (all",
+        "of them), or one smell kind such as feature_envy"
+      ]
+    ),
+    Flag.new(
+      name: "--skip", arg: "ANALYZERS", field: :skip, parse: Skip,
+      text: ["drop an analyzer; comma-separated: coupling,", "complexity, duplication, smells"]
+    ),
+    Flag.new(
+      name: "--package-by", arg: "WHAT", field: :packaging, parse: PackageBy,
+      text: [
+        "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"
+      ]
+    ),
+    Flag.new(
+      name: "--ratchet", mode: :ratchet,
+      text: ["fail when edges or findings appear that the", "baseline lacks"]
+    ),
+    Flag.new(name: "--update-baseline", mode: :update, text: ["record the current edges and findings"]),
+    Flag.new(
+      name: "--baseline", arg: "PATH", field: :baseline, default: "hashira_baseline.json",
+      text: ["baseline file (default: hashira_baseline.json)"]
+    ),
+    Flag.new(name: "-h, --help", mode: :help, text: ["print this help"]),
+    Flag.new(name: "--version", mode: :version, text: ["print the version"])
+  ].freeze
+end

data/lib/hashira/cli/format.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Hashira::CLI::Format
+  CHOICES = %w[text json dot mermaid].freeze
+
+  module_function
+
+  def parse(value)
+    return if value.empty?
+    return value.to_sym if CHOICES.include?(value)
+    raise(Hashira::Error.unknown("--format", value, CHOICES))
+  end
+end

data/lib/hashira/cli/options.rb

@@ -5,6 +5,8 @@ class Hashira::CLI
     Data.define(:directories, :mode, :baseline, :fail_on, :skip, :packaging) do
       def self.parse(argv) = CommandLine.new(argv).options
 
+      def self.page(mode) = new(directories: [], mode:, baseline: "", fail_on: [], skip: [], packaging: :auto)
+
       def pipeline
         Hashira::Pipeline.new(Hashira::Project.detect(directories), enabled: analyzers, packaging:)
       end

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(