hashira 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 53480df33daebb25ecac87a601cad36cc6a3d8657a5ccb3cd094c807e1be2c15
-  data.tar.gz: 6034a5afdfa48254a48b989405aed85e8e1d6c4f82dea35649d714edd8ed38ee
+  metadata.gz: 137dafce03e707a097cf684620fbd9c9efc8989347e77b88c13da103102f5da5
+  data.tar.gz: e0ab59d2e1909042c991764b5384217601aaf42b036bd6916042efc2107e0200
 SHA512:
-  metadata.gz: 915f8ea2649037c29a4971d4ebc3df94d38c6a976fd4f0792e3e2c80e3c54d23b776a3a511c0dd5fa7552cbbd6463282e9fcd31ba5e510c2a87d82aafbfb6310
-  data.tar.gz: 9b17e6bbc1625f7ed54d02eeb7ba8f345451c931e24cf39bd057bc8a06e92d11167d35a0bd1b883b75750aa533fdb39a1513dcb4359929c86d2cb0e21e285cdd
+  metadata.gz: 2c4895c6d045e05e610fda4c51ce763e0ef876049d933dbd4a3d9f99ac24c8648583a4a3f39e5c2baadfae263736914ba2a428781024ead0410b2d968585b8b8
+  data.tar.gz: dec6a978383a76ad57fdf34c98b5ea4b571775d44baafc0f5c02c3bbe75b7a56e274609c1586fc77af94e93f65f501579a5b6fa09bfd4db3952bb3cb412c153b

data/CHANGELOG.md

@@ -5,6 +5,44 @@ 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

data/README.md

@@ -476,6 +476,35 @@ 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

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

@@ -14,7 +14,7 @@ module Hashira
 
         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,18 +1,9 @@
 # frozen_string_literal: true
 
 class Hashira::Churn
-  LOG = %w[log --no-renames --name-only --format=].freeze
   SITES_THAT_DRIFT_APART = 2
 
-  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
+  def self.build(directory) = new(Hashira::GitLog.new(directory).counts)
 
   def initialize(counts)
     @counts = counts

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,16 +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) = new(Hashira::CI::Baseline.read(path).fetch("accepted", []))
+  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)
@@ -35,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

@@ -5,47 +5,37 @@ require "json"
 class Hashira::CI::Baseline
   SCHEMA_VERSION = 4
 
-  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, scope = Hashira::CI::Scope.none)
+  def initialize(path, analyzers: [], targets: [])
     @path = path
-    @recorded = recorded
-    @scope = scope
+    @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 = self.class.scored(@recorded.fetch("findings", {}))
+  def findings = keyed(recorded.fetch("findings", {}))
 
-  def self.scored(recorded) = recorded.is_a?(Array) ? recorded.to_h { [it, nil] } : recorded
+  def findings? = recorded.key?("findings")
 
-  def findings? = @recorded.key?("findings")
+  def accepted = recorded.fetch("accepted", [])
 
-  def packaging = @recorded.fetch("packaging", "folder")
+  def packaging = recorded.fetch("packaging", "folder")
 
-  def analyzers = @recorded.fetch("analyzers", wanted[:analyzers])
+  def analyzers = recorded.fetch("analyzers", wanted[:analyzers])
 
-  def targets = @recorded.fetch("targets", wanted[:targets])
+  def targets = recorded.fetch("targets", wanted[:targets])
 
-  def wanted = @scope.to_h
+  def wanted = scope.to_h
 
   def write(edges, findings, packaging:)
     File.write(@path, JSON.pretty_generate(payload(edges, findings, packaging)) << "\n")
@@ -53,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:, **@scope.to_h, 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

@@ -4,21 +4,6 @@ module Hashira
   module CI
     Diff =
       Data.define(:added, :removed, :worsened) do
-        def self.between(current, recorded)
-          new(
-            added: current.keys - recorded.keys, removed: recorded.keys - current.keys,
-            worsened: grown(current, recorded)
-          )
-        end
-
-        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 initialize(worsened: [], **) = super
         def empty? = added.empty? && removed.empty? && worsened.empty?
         def worse? = !added.empty? || !worsened.empty?

data/lib/hashira/ci/gate.rb

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
 class Hashira::CI::Gate
-  def initialize(findings, kinds, io: $stdout, err: $stderr)
+  def initialize(findings, kinds, io: $stdout, error: $stderr)
     @findings = findings
     @kinds = kinds
     @io = io
-    @err = err
+    @error = error
   end
 
   def check
@@ -19,7 +19,7 @@ class Hashira::CI::Gate
     offending.each { Hashira::Report::FindingLines.new(it, io: @io).print }
     verdict = "Gate FAILED: #{offending.size} finding(s) — #{tally(offending)}."
     @io.puts("\n#{verdict}")
-    @err.puts(verdict)
+    @error.puts(verdict)
     1
   end
 

data/lib/hashira/ci/ratchet.rb

@@ -14,7 +14,11 @@ class Hashira::CI::Ratchet
     Hashira::CI::Status::CLEAN
   end
 
-  def check = Hashira::CI::RatchetReport.new(@graph, @findings, io: @io).print(drift, delta)
+  def check(focus)
+    compared = focus.narrowing? ? Hashira::CI::Slice.new(@baseline) : Hashira::CI::Sweep.new(@baseline)
+    Hashira::CI::RatchetReport.new(@graph, @findings, io: @io)
+      .print(compared.edges(drift), delta(compared), tally(compared))
+  end
 
   def blocker
     return "no baseline at #{@baseline.path} — run --update-baseline first" unless @baseline.exist?
@@ -56,15 +60,17 @@ class Hashira::CI::Ratchet
 
   def edges = @graph.edges.map(&:to_s)
 
+  def tally(compared) = compared.counts("#{@graph.edges.size} edges", "#{@findings.size} findings").join(", ")
+
   def scored
-    @scored ||= @findings.group_by(&:signature).sort.to_h { |key, group| [key, group.filter_map(&:magnitude).max] }
+    @_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(scored, @baseline.findings) if @baseline.findings?
+  def delta(compared)
+    compared.findings(scored) if @baseline.findings?
   end
 end

data/lib/hashira/ci/ratchet_report.rb

@@ -7,8 +7,8 @@ class Hashira::CI::RatchetReport
     @io = io
   end
 
-  def print(edges, findings)
-    return unchanged if quiet?(edges, findings)
+  def print(edges, findings, tally)
+    return unchanged(tally) if quiet?(edges, findings)
     details(edges, findings)
     advice(edges, findings)
     verdict(edges, findings)
@@ -18,8 +18,8 @@ class Hashira::CI::RatchetReport
 
   def quiet?(*diffs) = diffs.compact.all?(&:empty?)
 
-  def unchanged
-    @io.puts("Ratchet OK: #{@graph.edges.size} edges, #{@findings.size} findings, unchanged.")
+  def unchanged(tally)
+    @io.puts("Ratchet OK: #{tally}, unchanged.")
     Hashira::CI::Status::CLEAN
   end
 

data/lib/hashira/ci/scope.rb

@@ -4,7 +4,6 @@ module Hashira
   module CI
     Scope =
       Data.define(:analyzers, :targets) do
-        def self.none = new(analyzers: [], targets: [])
         def to_h = { analyzers: analyzers.map(&:to_s).sort, targets: targets.sort }
       end
   end

data/lib/hashira/ci/slice.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+class Hashira::CI::Slice
+  SETTLED = Hashira::CI::Diff.new(added: [], removed: [])
+
+  def initialize(baseline)
+    @baseline = baseline
+  end
+
+  def edges(_diff) = SETTLED
+
+  def findings(scored) = Hashira::CI::Comparison.new(scored, seen(scored)).diff
+
+  def seen(scored) = @baseline.findings.slice(*scored.keys)
+
+  def counts(_edges, findings) = [findings]
+end

data/lib/hashira/ci/sweep.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+class Hashira::CI::Sweep
+  def initialize(baseline)
+    @baseline = baseline
+  end
+
+  def edges(diff) = diff
+
+  def findings(scored) = Hashira::CI::Comparison.new(scored, @baseline.findings).diff
+
+  def counts(edges, findings) = [edges, findings]
+end

data/lib/hashira/cli/arguments.rb

@@ -1,28 +1,32 @@
 # frozen_string_literal: true
 
 class Hashira::CLI::Arguments
-  def initialize(argv)
-    @argv = argv.dup
+  def initialize(given)
+    @given = given
   end
 
   def take(flag, default)
-    position = @argv.index(flag)
+    position = argv.index(flag)
     return default unless position
-    _flag, value = @argv.slice!(position, 2)
+    _flag, value = argv.slice!(position, 2)
     vet(flag, value)
   end
 
   def vet(flag, value)
     raise(Hashira::Error, "#{flag} needs a value") if value.to_s.strip.empty?
-    raise(Hashira::Error, "#{flag} given more than once") if @argv.include?(flag)
+    raise(Hashira::Error, "#{flag} given more than once") if argv.include?(flag)
     value
   end
 
-  def delete(flag) = @argv.delete(flag)
+  def delete(flag) = argv.delete(flag)
 
   def rest
-    stray = @argv.find { it.start_with?("-") }
+    stray = argv.find { it.start_with?("-") }
     raise(Hashira::Error, "unknown option #{stray}") if stray
-    @argv
+    argv
   end
+
+  private
+
+  def argv = @_argv ||= @given.dup
 end

data/lib/hashira/cli/choice.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Hashira::CLI::Choice
+  module_function
+
+  def unknown(flag, value, choices)
+    Hashira::Error.new("unknown #{flag} #{value.inspect} (use: #{choices.join(", ")})")
+  end
+end

data/lib/hashira/cli/command_line.rb

@@ -2,23 +2,26 @@
 
 class Hashira::CLI::CommandLine
   def initialize(argv)
-    @arguments = Hashira::CLI::Arguments.new(argv)
+    @argv = argv
   end
 
   def options = page || parsed
 
   private
 
+  def arguments = @_arguments ||= Hashira::CLI::Arguments.new(@argv)
+
   def page
     flag = Hashira::CLI::FLAGS.select(&:page?).find { seen?(it) }
-    Hashira::CLI::Options.page(flag.mode) if flag
+    Hashira::CLI::Options.build(flag.mode) if flag
   end
 
-  def seen?(flag) = flag.names.any? { @arguments.delete(it) }
+  def seen?(flag) = flag.names.any? { arguments.delete(it) }
 
   def parsed
-    parses = Hashira::CLI::FLAGS.reject(&:page?).to_h { [it, it.read(@arguments)] }
-    Hashira::CLI::Options.new(directories: @arguments.rest, mode: mode(parses), **fields(parses))
+    parses = Hashira::CLI::FLAGS.reject(&:page?).to_h { [it, it.read(arguments)] }
+    Hashira::CLI::Options.new(directories: arguments.rest, mode: mode(parses), **fields(parses))
+      .tap { Hashira::CLI::Needs.check(it) }
   end
 
   def fields(parses) = parses.to_h { |flag, value| [flag.field, value] }.except(nil)

data/lib/hashira/cli/fail_on.rb

@@ -5,12 +5,12 @@ require_relative "../pipeline"
 module Hashira::CLI::FailOn
   MEASURES = (Hashira::Pipeline::ANALYZERS - %i[coupling smells]).map(&:to_s).freeze
 
-  KINDS = {
-    "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
+  KINDS = { "cycles" => "cycle", "sdp" => "sdp_violation", "dupe" => "duplication" }
+    .merge(Hashira::Pipeline::STRUCTURAL.to_h { [it, it] })
+    .merge(MEASURES.to_h { [it, it] })
+    .merge("smells" => Hashira::Pipeline::SMELLS)
+    .merge(Hashira::Pipeline::SMELLS.to_h { [it, it] })
+    .freeze
 
   OWNERS = {
     **Hashira::Pipeline::STRUCTURAL.to_h { [it, :coupling] },

data/lib/hashira/cli/flag.rb

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
 
 class Hashira::CLI
+  BLANK = %i[arg field parse mode].to_h { [it, nil] }.freeze
+
   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 initialize(**attributes) = super(**BLANK, default: "", **attributes)
 
       def read(arguments) = arg ? take(arguments) : arguments.delete(name)
 

data/lib/hashira/cli/flags.rb

@@ -3,6 +3,7 @@
 require_relative "fail_on"
 require_relative "flag"
 require_relative "format"
+require_relative "only"
 require_relative "package_by"
 require_relative "skip"
 require_relative "top"
@@ -31,6 +32,15 @@ class Hashira::CLI
       name: "--skip", arg: "ANALYZERS", field: :skip, parse: Skip,
       text: ["drop an analyzer; comma-separated: coupling,", "complexity, duplication, smells"]
     ),
+    Flag.new(
+      name: "--only", arg: "PATHS", field: :only, parse: Only,
+      text: [
+        "keep only the findings that name these files;",
+        "comma-separated. The whole project is still read,",
+        "so cross-file signals stay right. Meant for hooks:",
+        "hashira --only $CHANGED --ratchet"
+      ]
+    ),
     Flag.new(
       name: "--top", arg: "N", field: :top, parse: Top,
       text: [

data/lib/hashira/cli/format.rb

@@ -8,6 +8,6 @@ module Hashira::CLI::Format
   def parse(value)
     return if value.empty?
     return value.to_sym if CHOICES.include?(value)
-    raise(Hashira::Error.unknown("--format", value, CHOICES))
+    raise(Hashira::CLI::Choice.unknown("--format", value, CHOICES))
   end
 end

data/lib/hashira/cli/needs.rb

@@ -12,10 +12,21 @@ module Hashira::CLI::Needs
     skip = options.skip
     drawing(mode, skip)
     gate(options.fail_on, skip)
-    shaping(mode) if options.compact
+    shaping(options, mode)
   end
 
-  def shaping(mode)
+  def shaping(options, mode)
+    compacting(mode) if options.compact
+    focusing(mode) unless options.only.empty?
+  end
+
+  def focusing(mode)
+    raise(Hashira::Error, "--only narrows the findings, but --update-baseline records them all") if mode == :update
+    return unless DIAGRAMS.include?(mode)
+    raise(Hashira::Error, "--format #{mode} draws the coupling graph, which --only cannot narrow")
+  end
+
+  def compacting(mode)
     raise(Hashira::Error, "--compact shapes JSON, but this run emits #{mode}") unless mode == :json
   end
 

data/lib/hashira/cli/only.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Hashira::CLI::Only
+  module_function
+
+  def parse(value)
+    return [] if value.empty?
+    value.split(",").map { vet(it.strip) }
+  end
+
+  def vet(path)
+    here = path.delete_prefix("#{Dir.pwd}/").delete_prefix("./")
+    raise(Hashira::Error, "--only #{path.inspect} is not a file here") unless File.file?(here)
+    here
+  end
+end