hashira 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a0b871ab3e0bf096a2752a48a4c3776d2dbe2ee0cae33b2df8af89649d0952ca
-  data.tar.gz: b1058810a8d965e1010044691d1b11571f21b077581f5e435d40b0d263f133b9
+  metadata.gz: 137dafce03e707a097cf684620fbd9c9efc8989347e77b88c13da103102f5da5
+  data.tar.gz: e0ab59d2e1909042c991764b5384217601aaf42b036bd6916042efc2107e0200
 SHA512:
-  metadata.gz: 24d9aae54c58e39a54799efdf9749f501000162c8ea8f9a38e02523fb6ee3122a98daf6591cfaf7816f3a2cd66f20218c08ff27579bc1b58a269e4ce7bddda92
-  data.tar.gz: 158bf3af24e081df3483e3d124833f6943404cfdab6ca1f2f7235115a400cfb1c48f885fb16b290fc529ebc1556c8eb5ed97119f635c9869ae881b44be51c599
+  metadata.gz: 2c4895c6d045e05e610fda4c51ce763e0ef876049d933dbd4a3d9f99ac24c8648583a4a3f39e5c2baadfae263736914ba2a428781024ead0410b2d968585b8b8
+  data.tar.gz: dec6a978383a76ad57fdf34c98b5ea4b571775d44baafc0f5c02c3bbe75b7a56e274609c1586fc77af94e93f65f501579a5b6fa09bfd4db3952bb3cb412c153b

data/CHANGELOG.md

@@ -5,6 +5,112 @@ 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.8.0] - 2026-08-15
+
+### Added
+
+- **`--only PATHS` narrows the findings to the files you name.** Meant for
+  hooks: after a formatter, a refactor, or an agent's edit, ask whether *these*
+  files got worse — `hashira --only "$CHANGED" --ratchet`. The whole project is
+  still parsed, because half of what hashira knows is cross-file (which
+  constants are yours, which methods reach into a neighbour, which fragments
+  are clones); reading one file alone would answer differently. A focused
+  ratchet stays quiet about package edges, which belong to no single file, and
+  about findings that disappeared, which only a whole-project run can confirm —
+  it reports what your files introduced or made worse. `--only` refuses
+  `--update-baseline` and the diagram formats, and ignores paths outside the
+  analyzed directories so a hook can hand it every changed file.
+
+### Changed
+
+- **Memoization stops reading as state.** An instance variable named `@_thing`
+  is a cache, not a responsibility: `instance_variable_assumption` no longer
+  reports lazy presence as an assumption, and `too_many_instance_variables`
+  no longer counts derived values against the class. Codebases that memoize
+  behind the `@_` convention will see both smells quieten; codebases that
+  don't are unaffected.
+- **Every object is built the way this tool says to build one.** Constructors
+  only assign, class-method logic dissolves into instances (`Project.detect`
+  and `CLI.run` are plain constructors — `exe/hashira` now calls
+  `CLI.new(argv).status`), factories are named `build`, and hashes acting as
+  objects got names (`SdpViolationFindings::Imbalance`,
+  `DuplicationFinding::Overlap`, `MethodFinding::Effort`). Internal
+  throughout: the command line, the reports, the JSON, and the baseline
+  format are unchanged. Only embedders calling the Ruby API directly are
+  affected.
+- Coupling reads its rule list from `Rule.subclasses`, the way the smells
+  report already read `Check.subclasses`, and parameters stop carrying their
+  node type (`def_node` → `definition`). hashira's own baseline is down to
+  zero findings and one accepted boundary.
+
+## [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,52 @@ 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.
 
+### Hooks: ratchet the files you just touched
+
+`--only` narrows the findings to the files you name, so an editor hook, a
+pre-commit hook, or an agent finishing an edit can ask the one question that
+matters there: *did these files get worse?*
+
+```sh
+hashira --only lib/billing/refund.rb,lib/orders/checkout.rb --ratchet
+hashira --only "$(git diff --cached --name-only -- '*.rb' | paste -sd, -)" --ratchet
+```
+
+The whole project is still parsed — that is the point. Half of what hashira knows
+is cross-file (which constants are yours, which methods pick apart a neighbour's
+internals, which fragments are clones of each other), so a file read alone would
+answer differently. `--only` narrows the *report*, never the analysis. On this
+repository a full run is under a second for 129 files; smells alone, a quarter of
+that.
+
+Two things a focused run cannot judge, and so stays quiet about: package edges,
+which belong to no single file, and findings that *disappeared*, which you would
+have to read the whole project to be sure of. It reports what your files
+introduced or made worse, and nothing else. Run the unfocused `--ratchet` in CI —
+that is where removals get celebrated and the baseline gets relocked.
+
+`--only` refuses to combine with `--update-baseline` (which would record a
+baseline missing everything you did not name) or with the diagram formats (which
+draw the graph, not the findings). Paths outside the analyzed directories are
+ignored, so a hook can hand it every changed file without filtering first.
+
+### 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 +549,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/exe/hashira

@@ -6,4 +6,4 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 
 require "hashira"
 
-exit Hashira::CLI.run(ARGV)
+exit Hashira::CLI.new(ARGV).status

data/lib/hashira/analysis/finding.rb

@@ -2,15 +2,19 @@
 
 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
+        def to_h = super.merge(detail: detail&.to_h).compact
       end
   end
 end

data/lib/hashira/analysis/syntax.rb

@@ -17,10 +17,10 @@ module Hashira
 
       def label(node) = [node.name.to_s]
 
-      def cbase?(node)
+      def rooted?(node)
         return false unless node.is_a?(Prism::ConstantPathNode)
         parent = node.parent
-        !parent || cbase?(parent)
+        !parent || rooted?(parent)
       end
 
       def anchor(stack, segments, roots)
@@ -33,12 +33,12 @@ module Hashira
         roots.include?(segments.first(1)) ? segments : (stack.last || []) + segments
       end
 
-      def direct(type_node) = statements(type_node).grep(Prism::DefNode)
+      def direct(type) = statements(type).grep(Prism::DefNode)
 
-      def constants(type_node) = statements(type_node).grep(Prism::ConstantWriteNode)
+      def constants(type) = statements(type).grep(Prism::ConstantWriteNode)
 
-      def statements(type_node)
-        body = type_node.body
+      def statements(type)
+        body = type.body
         body.is_a?(Prism::StatementsNode) ? body.body : [body]
       end
     end

data/lib/hashira/churn.rb

@@ -1,17 +1,16 @@
 # frozen_string_literal: true
 
 class Hashira::Churn
-  LOG = "git log --no-renames --name-only --format= 2>/dev/null"
   SITES_THAT_DRIFT_APART = 2
 
-  def self.scan = new(tally(`#{LOG}`))
-
-  def self.tally(output) = output.split("\n").map(&:strip).reject(&:empty?).tally
+  def self.build(directory) = new(Hashira::GitLog.new(directory).counts)
 
   def initialize(counts)
     @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

@@ -7,7 +7,7 @@ class Hashira::CI::Accepted
 
   Entry =
     Data.define(:kind, :package, :digest, :reason) do
-      def self.from(hash)
+      def self.build(hash)
         new(kind: hash["kind"], package: hash["package"], digest: hash["digest"], reason: hash["reason"])
       end
 
@@ -17,19 +17,16 @@ class Hashira::CI::Accepted
 
       def label = reason || "accepted (no reason recorded)"
 
-      def to_h = { kind:, package:, digest:, reason: }.compact
+      def to_h = super.compact
     end
 
-  def self.load(path)
-    return new([]) unless path && File.exist?(path)
-    new(JSON.parse(File.read(path)).fetch("accepted", []))
-  end
+  def self.build(path) = new(Hashira::CI::Baseline.new(path).accepted)
 
-  def initialize(entries)
-    @entries = entries.map { Entry.from(it) }
+  def initialize(list)
+    @list = list
   end
 
-  def entries = @entries.map(&:to_h)
+  def entries = records.map(&:to_h)
 
   def screen(findings)
     accepted, live = findings.map { [it, reason(it)] }.partition(&:last)
@@ -38,7 +35,9 @@ class Hashira::CI::Accepted
 
   private
 
+  def records = @_records ||= @list.map { Entry.build(it) }
+
   def reason(finding)
-    @entries.find { it.matches?(finding) }&.label
+    records.find { it.matches?(finding) }&.label
   end
 end

data/lib/hashira/ci/baseline.rb

@@ -3,26 +3,39 @@
 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 initialize(path, recorded)
+  def initialize(path, analyzers: [], targets: [])
     @path = path
-    @recorded = recorded
+    @analyzers = analyzers
+    @targets = targets
   end
 
   attr_reader :path
 
   def exist? = File.exist?(@path)
 
-  def edges = @recorded.fetch("edges", [])
+  def trouble
+    recorded && 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 edges = recorded.fetch("edges", [])
+
+  def findings = keyed(recorded.fetch("findings", {}))
+
+  def findings? = recorded.key?("findings")
+
+  def accepted = recorded.fetch("accepted", [])
+
+  def packaging = recorded.fetch("packaging", "folder")
 
-  def findings = @recorded.fetch("findings", [])
+  def analyzers = recorded.fetch("analyzers", wanted[:analyzers])
 
-  def findings? = @recorded.key?("findings")
+  def targets = recorded.fetch("targets", wanted[:targets])
 
-  def packaging = @recorded.fetch("packaging", "folder")
+  def wanted = scope.to_h
 
   def write(edges, findings, packaging:)
     File.write(@path, JSON.pretty_generate(payload(edges, findings, packaging)) << "\n")
@@ -30,9 +43,23 @@ class Hashira::CI::Baseline
 
   private
 
+  def recorded
+    @_recorded ||= read
+  end
+
+  def read
+    return {} unless @path && File.exist?(@path)
+    stored = JSON.parse(File.read(@path))
+    stored.is_a?(Hash) ? stored : raise(JSON::ParserError, "its top level is a list, not an object")
+  end
+
+  def keyed(findings) = findings.is_a?(Array) ? findings.to_h { [it, nil] } : findings
+
+  def scope = Hashira::CI::Scope.new(analyzers: @analyzers, targets: @targets)
+
   def payload(edges, findings, packaging)
-    base = { version: SCHEMA_VERSION, packaging:, edges:, findings: }
-    accepted = Hashira::CI::Accepted.new(@recorded.fetch("accepted", [])).entries
-    accepted.empty? ? base : base.merge(accepted:)
+    base = { version: SCHEMA_VERSION, packaging: }.merge(scope.to_h).merge(edges:, findings:)
+    kept = Hashira::CI::Accepted.new(accepted).entries
+    kept.empty? ? base : base.merge(accepted: kept)
   end
 end

data/lib/hashira/ci/comparison.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+class Hashira::CI::Comparison
+  def initialize(current, recorded)
+    @current = current
+    @recorded = recorded
+  end
+
+  def diff
+    current = @current.keys
+    recorded = @recorded.keys
+    Hashira::CI::Diff.new(added: current - recorded, removed: recorded - current, worsened:)
+  end
+
+  private
+
+  def worsened
+    (@current.keys & @recorded.keys).filter_map { entry(it, @recorded[it], @current[it]) }
+  end
+
+  def entry(key, before, after)
+    [key, before, after] if before.is_a?(Integer) && after.is_a?(Integer) && after > before
+  end
+end

data/lib/hashira/ci/diff.rb

@@ -3,14 +3,10 @@
 module Hashira
   module CI
     Diff =
-      Data.define(:added, :removed) do
-        def self.between(current, recorded)
-          new(added: current - recorded, removed: recorded - current)
-        end
-
-        def empty? = added.empty? && removed.empty?
-
-        def worse? = !added.empty?
+      Data.define(:added, :removed, :worsened) do
+        def initialize(worsened: [], **) = super
+        def empty? = added.empty? && removed.empty? && worsened.empty?
+        def worse? = !added.empty? || !worsened.empty?
       end
   end
 end