hashira 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a0b871ab3e0bf096a2752a48a4c3776d2dbe2ee0cae33b2df8af89649d0952ca
-  data.tar.gz: b1058810a8d965e1010044691d1b11571f21b077581f5e435d40b0d263f133b9
+  metadata.gz: 53480df33daebb25ecac87a601cad36cc6a3d8657a5ccb3cd094c807e1be2c15
+  data.tar.gz: 6034a5afdfa48254a48b989405aed85e8e1d6c4f82dea35649d714edd8ed38ee
 SHA512:
-  metadata.gz: 24d9aae54c58e39a54799efdf9749f501000162c8ea8f9a38e02523fb6ee3122a98daf6591cfaf7816f3a2cd66f20218c08ff27579bc1b58a269e4ce7bddda92
-  data.tar.gz: 158bf3af24e081df3483e3d124833f6943404cfdab6ca1f2f7235115a400cfb1c48f885fb16b290fc529ebc1556c8eb5ed97119f635c9869ae881b44be51c599
+  metadata.gz: 915f8ea2649037c29a4971d4ebc3df94d38c6a976fd4f0792e3e2c80e3c54d23b776a3a511c0dd5fa7552cbbd6463282e9fcd31ba5e510c2a87d82aafbfb6310
+  data.tar.gz: 9b17e6bbc1625f7ed54d02eeb7ba8f345451c931e24cf39bd057bc8a06e92d11167d35a0bd1b883b75750aa533fdb39a1513dcb4359929c86d2cb0e21e285cdd

data/CHANGELOG.md

@@ -5,6 +5,74 @@ 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.7.0] - 2026-08-10
+
+### Added
+
+- **The ratchet compares magnitudes, not just identities.** The baseline now
+  records a value beside each finding's signature — cognitive complexity,
+  clone-cluster mass — so a baselined method that gets measurably worse fails
+  the build instead of hiding behind set membership. On a legacy codebase this
+  is the case the ratchet exists for: everything hot is already baselined on
+  day one.
+- **Exit codes stop meaning six different things.** 0 clean, 1 findings or a
+  caught regression, 2 misuse, 3 an improvement the baseline has not recorded,
+  70 internal error. Failing on 1 while treating 3 as a nudge blocks
+  regressions without blocking progress. Unexpected exceptions now print the
+  class, message, origin frame, and where to report — not a backtrace.
+- **The report says what produced it.** The heading names the packaging mode,
+  files Ruby itself rejects are counted and named on stderr instead of
+  contributing half-parsed trees silently, and a terminal run shows a sign of
+  life before the parse and a timing line after (never when stderr is not a
+  tty — stdout stays byte-identical).
+- `--top N` caps every list at once; the package table and findings list gain
+  a default cap of 25 with a note saying what was withheld. `--json` is never
+  capped.
+- `--compact` emits `--json` on one line instead of pretty-printed
+  indentation, and `--json` now opens with schema version, packaging, targets,
+  and file count.
+
+### Fixed
+
+- **Green no longer means unchecked.** `--fail-on ""` armed nothing and
+  passed; `--fail-on cycles --skip coupling` switched off the only analyzer
+  that finds cycles and announced there were none; a directory with no Ruby
+  files was congratulated on its healthy structure. All three now fail
+  loudly.
+- **The baseline guards the whole scope it was recorded under.** A baseline
+  recorded over four analyzers, compared against a run with `--skip smells`,
+  reported every smell finding as an improvement and suggested locking it in.
+  Schema 4 records analyzers and target directories, and the ratchet refuses
+  a mismatched run the same way the packaging guard already did.
+- Churn runs `git -C <directory>` instead of reading the working directory,
+  so analyzing a repo from anywhere else no longer zeroes every count and
+  silently reorders the hotspot queue. A run with no history says so; an
+  unreadable baseline is a one-line error, not nine frames of Ruby.
+- Five CLI misreadings: a file argument is named as a file (with the
+  directory to try), duplicate directories are deduplicated by realpath, a
+  gem whose lib holds only loose files is accepted, a value flag given twice
+  is not "unknown", and a diagram whose analyzer is skipped is refused
+  instead of drawn anyway.
+- Diagrams stop losing packages: mermaid/dot ids are generated so `my-pkg`
+  and `my_pkg` no longer merge (and a package named `end` no longer breaks
+  the grammar), and isolated packages appear instead of vanishing.
+- `Gate FAILED` names the kinds that actually fired, worst first, mirrored to
+  stderr; `--update-baseline` and `--ratchet` no longer report contradictory
+  totals for the same run.
+- Tables size their columns to their contents: long names clip in the middle
+  instead of pushing rows into ribbons, numeric columns right-align, and
+  trailing whitespace is gone.
+- An edgeless package prints "—" and sorts last instead of claiming I=0.00
+  beside genuine foundations.
+
+### Changed
+
+- The four house cops and shared style defaults moved to the published
+  `rubocop-kata` gem; `.rubocop.yml` keeps only project-specific config.
+- Docs: the `--fail-on` shorthands (`cycles`, `sdp`, `dupe`) are documented,
+  and a bare `hashira` in a Rails root notes once on stderr that `hashira app`
+  reads the application.
+
 ## [0.6.0] - 2026-08-05
 
 ### Changed

data/README.md

@@ -21,10 +21,12 @@ the cycle and to the cheapest edge to cut:
 
 ```console
 $ hashira app
-package       TC  Ca  Ce     I  Cyc
-----------------------------------------
-billing        1   1   1  0.50  YES
-shipping       1   1   1  0.50  YES
+Package (folder) metrics for app  (2 packages, 2 files)
+
+package   TC  Ca  Ce     I  Cyc
+-------------------------------
+billing    1   1   1  0.50  YES
+shipping   1   1   1  0.50  YES
 
 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).
@@ -72,66 +74,77 @@ Single-folder wrapper chains are descended automatically, so `hashira`,
 hashira                        # auto-detects lib/<gem>
 hashira lib/myapp              # or point it at a directory
 hashira app lib                # or several — one shared graph
-hashira --skip complexity,duplication   # coupling only
-hashira --skip coupling                 # complexity + duplication
+hashira --skip complexity,duplication   # coupling + smells only
+hashira --skip coupling                 # complexity + duplication + smells
+hashira --top 50                        # longer tables and findings list
 ```
 
 The full text report is the coupling tables, the complexity tables, the hotspot
-rollup, and the findings (which include any duplication clusters). Here it is on
-hashira's own source:
+rollup, and the findings (which include any duplication clusters). It is capped
+so a large codebase stays readable — 25 packages and findings, 10 methods and
+files — and every list says how many rows it withheld. `--top N` moves all of
+them at once; `--json` is never capped.
+
+The heading names the packaging that ran (`folder` or `namespace`), since the
+baseline is recorded per mode. Anything hashira had to work around goes to
+stderr, never stdout: a directory with no git history (churn reads as zero, so
+hotspots rank by cost alone), and files Prism could not parse. On a terminal
+you also get a progress line before the parse and a timing line after; piped or
+in CI, stdout is byte-identical either way. Here it is on hashira's own source:
 
 ```console
 $ hashira
-Package (layer) metrics for lib/hashira  (11 packages, 111 files)
-
-package       TC  Ca  Ce     I  Cyc
-----------------------------------------
-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  -
-coupling      24   1   1  0.50  -
-smells        21   1   1  0.50  -
-(root)         4   1   5  0.83  -
-cli            8   0   4  1.00  -
+Package (folder) metrics for lib/hashira  (11 packages, 129 files)
+
+package      TC  Ca  Ce     I  Cyc
+----------------------------------
+diagram       3   1   0  0.00  -
+hotspots      1   1   0  0.00  -
+analysis      3   4   0  0.00  -
+report       11   2   1  0.33  -
+duplication  14   2   1  0.33  -
+smells       24   1   1  0.50  -
+ci            8   1   1  0.50  -
+complexity    7   1   1  0.50  -
+coupling     29   1   1  0.50  -
+(root)        5   1   5  0.83  -
+cli          11   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)       -> complexity(1), coupling(5), duplication(1), hotspots(1), smells(1) <- cli
+  (root)       -> complexity(1), coupling(2), duplication(1), hotspots(1), smells(3) <- cli
   analysis     -> (none)                           <- complexity, coupling, duplication, smells
   duplication  -> analysis(3)                      <- (root), report
   ...
 
 Cognitive complexity — worst methods (Cog = how hard to read, Calls = message sends):
 
-method                                        Cog  Calls  Loc
--------------------------------------------------------------
-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
+method                                      Cog  Calls  Loc
+---------------------------------------------------------------------------------------
+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               4      6  coupling/roster.rb:22
 ...
 
 Per-class rollup (Cog total survives extract-method; Peak is the worst method it hides):
 
-class                              Cog  Methods   Peak
-------------------------------------------------------
-Hashira::Project                    12       15      3
-Hashira::CLI::CommandLine           12       15      3
+class                           Cog  Methods  Peak
+--------------------------------------------------
+Hashira::Project                 13       15     3
+Hashira::Smells::Conditions      11        9     4
+Hashira::Smells::Foreign         11       27     1
 ...
 
 Hotspots — cost × churn (where refactoring pays the most):
 
-file                                             Cog   Dup  Churn    Rank
--------------------------------------------------------------------------
-pipeline.rb                                       10     0      6      60
-cli/command_line.rb                               12     0      4      48
-project.rb                                        12     0      4      48
+file                     Cog  Dup  Churn  Rank
+----------------------------------------------
+pipeline.rb               10    0     11   110
+project.rb                13    0      5    65
+report/text.rb             8    0      4    32
 ...
 
 Findings (0):
@@ -185,11 +198,13 @@ reach into `Ci`?
 
 ```console
 $ hashira app
-package       TC  Ca  Ce     I  Cyc
-----------------------------------------
-Account       26  21  18  0.46  YES
-Billing      116  12  11  0.48  YES
-Ci           107   9  16  0.64  YES
+Package (namespace) metrics for app  (442 packages, 3222 files)
+
+package   TC  Ca  Ce     I  Cyc
+-------------------------------
+Account   26  21  18  0.46  YES
+Billing  116  12  11  0.48  YES
+Ci       107   9  16  0.64  YES
 ...
   cycle: Account can reach itself: Account -> User -> Account — any change
   may ripple back around. The lightest edge on this cycle is Account -> User (1 ref).
@@ -355,13 +370,13 @@ changes — because cost you never pay isn't worth paying down:
 ```console
 Hotspots — cost × churn (where refactoring pays the most):
 
-file                                             Cog   Dup  Churn    Rank
--------------------------------------------------------------------------
-controllers/orders/refunds_controller.rb           0    67      4     268
-controllers/orders/returns_controller.rb           0    67      4     268
-models/invoice.rb                                  8    34      3     126
-models/shipping/label.rb                           9   100      1     109
-controllers/orders_controller.rb                   8     0      7      56
+file                                      Cog  Dup  Churn  Rank
+---------------------------------------------------------------
+controllers/orders/refunds_controller.rb    0   67      4   268
+controllers/orders/returns_controller.rb    0   67      4   268
+models/invoice.rb                           8   34      3   126
+models/shipping/label.rb                    9  100      1   109
+controllers/orders_controller.rb            8    0      7    56
 ```
 
 Read it as a work queue: the top row is where a day of refactoring buys the most.
@@ -412,6 +427,12 @@ at all. It only works on a codebase that starts clean.
 hashira --fail-on cycles,sdp,mixed_audience,wide_edge,roll_call,smells   # any subset
 ```
 
+Kinds are named as the reports name them, plus three shorthands: `cycles` for
+`cycle`, `sdp` for `sdp_violation`, and `dupe` for `duplication`. `smells`
+expands to every smell kind; a single smell can be named on its own
+(`--fail-on feature_envy`). An unknown kind lists the valid ones rather than
+guessing.
+
 The ratchet is the one you can adopt today. Commit a baseline of what's true now
 — which edges exist, which findings stand — and the build fails when that set
 *grows*. It never asks whether the code is good, only whether this commit made it
@@ -423,6 +444,22 @@ hashira --ratchet                # fail if either set grew
 hashira --ratchet --baseline PATH
 ```
 
+The baseline records more than which findings exist: where a finding has a
+magnitude — cognitive complexity, clone mass, sprawl count — it records that too.
+So a method already in the baseline going from 10 to 54 is a regression, not
+"unchanged". On a legacy codebase, where most hot methods are baselined on day
+one, that is where the work actually happens:
+
+```console
+$ hashira --ratchet
+WORSE FINDING (was 13, now 24):
+  complexity: App::Core::Knot#tangle — cognitive 24, 1 calls (core/knot.rb:4).
+  flatten the branching — guard clauses, early returns, or polymorphism.
+```
+
+Baselines written by earlier versions still work: they record identity only, so
+they ratchet on appearance until the next `--update-baseline` records magnitudes.
+
 A regression prints in full, with the evidence that introduced it:
 
 ```console
@@ -439,6 +476,23 @@ record the decision: update the baseline, or accept it with a reason.
 Improvements fail the build too, and say so cheerfully — an unrecorded gain is one
 the next commit can quietly undo. Re-run `--update-baseline` to lock it in.
 
+### Exit codes
+
+A build step should be able to tell a regression from a typo without grepping
+English, so the codes are distinct:
+
+| code | meaning |
+| ---- | ------- |
+| `0`  | clean — nothing found, or nothing worse than the baseline |
+| `1`  | findings, or the ratchet found a regression |
+| `2`  | misuse — bad flags, missing directory, unusable baseline |
+| `3`  | an improvement the baseline has not recorded yet |
+| `70` | internal error, worth reporting |
+
+`3` is the one worth wiring specially: it means the code got better and only the
+baseline is stale. Failing on `1` while treating `3` as a nudge lets a build
+block regressions without blocking progress.
+
 ### Accepting by design
 
 Anything deliberate goes in the baseline with a reason. It leaves reports and
@@ -466,12 +520,24 @@ sentence turns every exception into a decision somebody reviewed.
 ## Other formats
 
 ```sh
-hashira --json            # machine format: findings (with digests), accepted, packages,
-                          # edges, complexity, duplication, hotspots
+hashira --json            # machine format, never capped by --top
+hashira --json --compact  # the same on one line, for piping
 hashira --format dot      # Graphviz digraph
 hashira --format mermaid  # Mermaid diagram
 ```
 
+`--json` opens with what produced it — `version` (the schema, bumped when the
+shape changes), `packaging`, `targets`, `files` — then `findings` (each with its
+`digest`), `accepted`, `packages`, `edges`, `folds` (single-type classes joined
+to a base or domain, `{from, to, via}`), `complexity`, `duplication`, and
+`hotspots`. A package with no edges at all reports `"i": null` rather than
+pretending 0/0 is maximally stable.
+
+Both diagrams declare every package before the arrows, so a package nothing
+depends on still appears. Mermaid node ids are generated (`p0`, `p1`, …) with
+the real name in the label, so `my-pkg` and `my_pkg` stay two nodes and a
+package called `end` does not break the graph.
+
 ## Why cognitive complexity
 
 The older Ruby complexity metrics charge roughly one point per message send and

data/lib/hashira/analysis/finding.rb

@@ -2,12 +2,16 @@
 
 module Hashira
   module Analysis
+    MAGNITUDES = { "complexity" => :cognitive, "duplication" => :mass, "boundary_sprawl" => :count }.freeze
+
     Finding =
       Data.define(:kind, :package, :detail, :evidence, :cycle, :digest) do
         def initialize(cycle: nil, digest: nil, detail: nil, **rest) = super
 
         def signature = "#{kind}:#{identity}"
 
+        def magnitude = detail.to_h[MAGNITUDES[kind]]
+
         def identity = digest || package
 
         def to_h = super.compact

data/lib/hashira/churn.rb

@@ -1,10 +1,16 @@
 # frozen_string_literal: true
 
 class Hashira::Churn
-  LOG = "git log --no-renames --name-only --format= 2>/dev/null"
+  LOG = %w[log --no-renames --name-only --format=].freeze
   SITES_THAT_DRIFT_APART = 2
 
-  def self.scan = new(tally(`#{LOG}`))
+  def self.scan(directory) = new(tally(read(directory)))
+
+  def self.read(directory)
+    IO.popen(["git", "-C", directory, *LOG], err: File::NULL, &:read)
+  rescue SystemCallError
+    ""
+  end
 
   def self.tally(output) = output.split("\n").map(&:strip).reject(&:empty?).tally
 
@@ -12,6 +18,8 @@ class Hashira::Churn
     @counts = counts
   end
 
+  def history? = @counts.any?
+
   def hits(file) = @counts.select { |path, _| path.end_with?(file) }.values.max || 0
 
   def hot?(members) = changing(members) >= SITES_THAT_DRIFT_APART

data/lib/hashira/ci/accepted.rb

@@ -20,10 +20,7 @@ class Hashira::CI::Accepted
       def to_h = { kind:, package:, digest:, reason: }.compact
     end
 
-  def self.load(path)
-    return new([]) unless path && File.exist?(path)
-    new(JSON.parse(File.read(path)).fetch("accepted", []))
-  end
+  def self.load(path) = new(Hashira::CI::Baseline.read(path).fetch("accepted", []))
 
   def initialize(entries)
     @entries = entries.map { Entry.from(it) }

data/lib/hashira/ci/baseline.rb

@@ -3,13 +3,28 @@
 require "json"
 
 class Hashira::CI::Baseline
-  SCHEMA_VERSION = 3
+  SCHEMA_VERSION = 4
 
-  def self.load(path) = new(path, File.exist?(path) ? JSON.parse(File.read(path)) : {})
+  def self.load(path, analyzers: [], targets: [])
+    new(path, read(path), Hashira::CI::Scope.new(analyzers:, targets:))
+  end
+
+  def self.read(path)
+    return {} unless path && File.exist?(path)
+    recorded = JSON.parse(File.read(path))
+    recorded.is_a?(Hash) ? recorded : raise(JSON::ParserError, "its top level is a list, not an object")
+  end
+
+  def self.trouble(path)
+    read(path) && nil
+  rescue JSON::ParserError, SystemCallError => error
+    "#{path} is not a usable baseline — #{error.message.lines.first.strip}. Re-record it with --update-baseline"
+  end
 
-  def initialize(path, recorded)
+  def initialize(path, recorded, scope = Hashira::CI::Scope.none)
     @path = path
     @recorded = recorded
+    @scope = scope
   end
 
   attr_reader :path
@@ -18,12 +33,20 @@ class Hashira::CI::Baseline
 
   def edges = @recorded.fetch("edges", [])
 
-  def findings = @recorded.fetch("findings", [])
+  def findings = self.class.scored(@recorded.fetch("findings", {}))
+
+  def self.scored(recorded) = recorded.is_a?(Array) ? recorded.to_h { [it, nil] } : recorded
 
   def findings? = @recorded.key?("findings")
 
   def packaging = @recorded.fetch("packaging", "folder")
 
+  def analyzers = @recorded.fetch("analyzers", wanted[:analyzers])
+
+  def targets = @recorded.fetch("targets", wanted[:targets])
+
+  def wanted = @scope.to_h
+
   def write(edges, findings, packaging:)
     File.write(@path, JSON.pretty_generate(payload(edges, findings, packaging)) << "\n")
   end
@@ -31,7 +54,7 @@ class Hashira::CI::Baseline
   private
 
   def payload(edges, findings, packaging)
-    base = { version: SCHEMA_VERSION, packaging:, edges:, findings: }
+    base = { version: SCHEMA_VERSION, packaging:, **@scope.to_h, edges:, findings: }
     accepted = Hashira::CI::Accepted.new(@recorded.fetch("accepted", [])).entries
     accepted.empty? ? base : base.merge(accepted:)
   end

data/lib/hashira/ci/diff.rb

@@ -3,14 +3,25 @@
 module Hashira
   module CI
     Diff =
-      Data.define(:added, :removed) do
+      Data.define(:added, :removed, :worsened) do
         def self.between(current, recorded)
-          new(added: current - recorded, removed: recorded - current)
+          new(
+            added: current.keys - recorded.keys, removed: recorded.keys - current.keys,
+            worsened: grown(current, recorded)
+          )
         end
 
-        def empty? = added.empty? && removed.empty?
+        def self.grown(current, recorded)
+          (current.keys & recorded.keys).filter_map { entry(it, recorded[it], current[it]) }
+        end
+
+        def self.entry(key, before, after)
+          [key, before, after] if before.is_a?(Integer) && after.is_a?(Integer) && after > before
+        end
 
-        def worse? = !added.empty?
+        def initialize(worsened: [], **) = super
+        def empty? = added.empty? && removed.empty? && worsened.empty?
+        def worse? = !added.empty? || !worsened.empty?
       end
   end
 end

data/lib/hashira/ci/finding_diff_report.rb

@@ -8,6 +8,7 @@ class Hashira::CI::FindingDiffReport
 
   def print(diff)
     introduced(diff.added).each { emit(it) }
+    aggravated(diff.worsened).each { |finding, before, after| regressed(finding, before, after) }
     Hashira::CI::Improvement.new("Findings resolved", io: @io).print(diff.removed)
   end
 
@@ -15,6 +16,15 @@ class Hashira::CI::FindingDiffReport
 
   def introduced(added) = added.filter_map { |signature| @findings.find { it.signature == signature } }
 
+  def aggravated(worsened)
+    worsened.map { |signature, before, after| [@findings.find { it.signature == signature }, before, after] }
+  end
+
+  def regressed(finding, before, after)
+    @io.puts("WORSE FINDING (was #{before}, now #{after}):")
+    Hashira::Report::FindingLines.new(finding, indent: "  ", io: @io).emit
+  end
+
   def emit(finding)
     @io.puts("NEW FINDING:")
     Hashira::Report::FindingLines.new(finding, indent: "  ", io: @io).emit

data/lib/hashira/ci/gate.rb

@@ -1,10 +1,11 @@
 # frozen_string_literal: true
 
 class Hashira::CI::Gate
-  def initialize(findings, kinds, io: $stdout)
+  def initialize(findings, kinds, io: $stdout, err: $stderr)
     @findings = findings
     @kinds = kinds
     @io = io
+    @err = err
   end
 
   def check
@@ -16,10 +17,17 @@ class Hashira::CI::Gate
 
   def failure(offending)
     offending.each { Hashira::Report::FindingLines.new(it, io: @io).print }
-    @io.puts("\nGate FAILED: #{offending.size} finding(s) of kind #{@kinds.join(", ")}.")
+    verdict = "Gate FAILED: #{offending.size} finding(s) — #{tally(offending)}."
+    @io.puts("\n#{verdict}")
+    @err.puts(verdict)
     1
   end
 
+  def tally(offending)
+    offending.group_by(&:kind).map { |kind, list| [kind, list.size] }
+      .sort_by { |kind, size| [-size, kind] }.map { |kind, size| "#{kind} #{size}" }.join(", ")
+  end
+
   def clean
     @io.puts("Gate OK: no findings of kind #{@kinds.join(", ")}.")
     0

data/lib/hashira/ci/improvement.rb

@@ -9,6 +9,6 @@ class Hashira::CI::Improvement
   def print(removed)
     return if removed.empty?
     @io.puts("#{@label} (improvement!): #{removed.join(", ")}")
-    @io.puts("Lock it in: hashira --update-baseline")
+    @io.puts("Lock it in: re-run this command with --update-baseline")
   end
 end

data/lib/hashira/ci/ratchet.rb

@@ -1,30 +1,53 @@
 # frozen_string_literal: true
 
 class Hashira::CI::Ratchet
-  def initialize(graph, findings, baseline_path, io: $stdout)
+  def initialize(graph, findings, baseline, io: $stdout)
     @graph = graph
     @findings = findings
-    @baseline = Hashira::CI::Baseline.load(baseline_path)
+    @baseline = baseline
     @io = io
   end
 
   def update
-    @baseline.write(edges, digests, packaging:)
-    @io.puts("Baseline updated: #{edges.size} edges, #{digests.size} findings.")
-    0
+    @baseline.write(edges, scored, packaging:)
+    @io.puts("Baseline updated: #{edges.size} edges, #{recorded}.")
+    Hashira::CI::Status::CLEAN
   end
 
   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
+    drifted.first
   end
 
   private
 
+  def drifted = [(mismatch unless @baseline.packaging == packaging), *narrowed(@baseline.wanted)].compact
+
+  def narrowed(wanted)
+    [
+      widened("the analyzers", @baseline.analyzers, wanted[:analyzers]),
+      widened("the directories", @baseline.targets, wanted[:targets])
+    ]
+  end
+
+  def widened(flag, was, now)
+    return if was == now
+    phrase(flag, was, now)
+  end
+
+  def phrase(flag, was, now)
+    "baseline #{@baseline.path} was recorded with #{flag} #{was.join(", ")}, but this run " \
+      "uses #{now.join(", ")} — rerun the recorded way, or refresh it with --update-baseline"
+  end
+
   def packaging = @graph.packaging.to_s
 
+  def recorded = collapsed(@findings.size, scored.size)
+
+  def collapsed(total, keys) = keys == total ? "#{total} findings" : "#{total} findings (#{keys} distinct)"
+
   def mismatch
     recorded = @baseline.packaging
     "baseline #{@baseline.path} was recorded with --package-by #{recorded}, but this run " \
@@ -33,13 +56,15 @@ class Hashira::CI::Ratchet
 
   def edges = @graph.edges.map(&:to_s)
 
-  def digests = @findings.map(&:signature).uniq.sort
+  def scored
+    @scored ||= @findings.group_by(&:signature).sort.to_h { |key, group| [key, group.filter_map(&:magnitude).max] }
+  end
 
   def drift = Hashira::CI::Diff.new(added: fresh, removed: @baseline.edges - edges)
 
   def fresh = @graph.edges.reject { @baseline.edges.include?(it.to_s) }
 
   def delta
-    Hashira::CI::Diff.between(digests, @baseline.findings) if @baseline.findings?
+    Hashira::CI::Diff.between(scored, @baseline.findings) if @baseline.findings?
   end
 end

data/lib/hashira/ci/ratchet_report.rb

@@ -11,7 +11,7 @@ class Hashira::CI::RatchetReport
     return unchanged if quiet?(edges, findings)
     details(edges, findings)
     advice(edges, findings)
-    1
+    verdict(edges, findings)
   end
 
   private
@@ -20,9 +20,11 @@ class Hashira::CI::RatchetReport
 
   def unchanged
     @io.puts("Ratchet OK: #{@graph.edges.size} edges, #{@findings.size} findings, unchanged.")
-    0
+    Hashira::CI::Status::CLEAN
   end
 
+  def verdict(*diffs) = diffs.compact.any?(&:worse?) ? Hashira::CI::Status::WORSE : Hashira::CI::Status::BETTER
+
   def details(edges, findings)
     Hashira::CI::EdgeDiffReport.new(@graph, io: @io).print(edges)
     Hashira::CI::FindingDiffReport.new(@findings, io: @io).print(findings) if findings