rigortype 0.4.6 → 0.4.8

data/lib/rigor/cli/coverage_command.rb

@@ -68,7 +68,7 @@ module Rigor
         configuration = Configuration.load(options.fetch(:config))
         paths = resolve_paths(configuration)
         return CLI::EXIT_USAGE if paths.nil?
-        return usage_error if paths.empty?
+        return no_ruby_files_error(configuration) if paths.empty?
 
         return run_protection(paths, options, configuration) if options[:protection]
 
@@ -77,27 +77,31 @@ module Rigor
         determine_exit(report, options)
       end
 
+      # The parser this command parses with, built without parsing anything (the catalogue reads it, ADR-126 WD3).
+      def option_parser(options = {})
+        OptionParser.new { |opts| define_options(opts, options) }
+      end
+
       private
 
-      # Like `rigor check`, fall back to the configured `paths:` when no path is given on the command line
-      # (`coverage` previously required an explicit path — operational friction the two commands should not
-      # differ on). The mutation mode keeps its own git-changed-files default and returns before this.
+      # Like `rigor check`, fall back to the configured `paths:` when no path is given. The mutation mode keeps its own
+      # git-changed-files default and returns before this.
       def resolve_paths(configuration)
         args = @argv.empty? ? configuration.paths : @argv
-        collect_paths(args, command_name: "coverage")
+        collect_paths_reporting(args)
       end
 
       def parse_options
         options = { format: "text", threshold: nil, config: nil, protection: false, mutation: false,
                     with_tests: false, test_command: DEFAULT_TEST_COMMAND, include_dynamic: false,
                     limit: nil, seed: 1, workers: nil, no_cache: false }
-        OptionParser.new { |opts| define_options(opts, options) }.parse!(@argv)
+        option_parser(options).parse!(@argv)
         options
       end
 
       def define_options(opts, options)
         opts.banner = USAGE
-        opts.on("--format=FORMAT", "Output format: text or json") { |v| options[:format] = v }
+        Options.add_format(opts, options, "Output format: text or json")
         Options.add_config(opts, options)
         opts.on("--protection", "Report type-protection coverage (ADR-63 Tier 1) instead of type precision") do
           options[:protection] = true
@@ -203,7 +207,7 @@ module Rigor
       #   `singleton(Account)` instead of `Dynamic`. Without this, a
       #   single-file scan cannot see a class it does not itself declare,
       #   so every cross-file class-constant dispatch was miscounted as
-      #   unprotected (the model-constant undercount found 2026-07-04).
+      #   unprotected.
       # - `param_inferred_types` (ADR-67 WD3) — an inferred-parameter
       #   receiver (`node.loc` where `node` is a `def compile(node)`
       #   parameter) counts as protected when its call sites resolve to
@@ -253,6 +257,15 @@ module Rigor
         CLI::EXIT_USAGE
       end
 
+      # #2206 — paths were named, or configured, but none holds a Ruby file. Said as such, not as "no path given".
+      def no_ruby_files_error(configuration)
+        return usage_error if @argv.empty? && Array(configuration.paths).empty?
+
+        @err.puts("coverage: no Ruby files under the given paths")
+        @err.puts(USAGE)
+        CLI::EXIT_USAGE
+      end
+
       def scan_paths(paths, configuration)
         CoverageScan.precision_report(files: paths, configuration: configuration)
       end

data/lib/rigor/cli/coverage_mutation.rb

@@ -24,7 +24,6 @@ module Rigor
       DISCOVERY_SEEDED_MUTATION_SITES = "discovery-seeded-mutation-sites"
 
       # ADR-50 § WD2 — the bleeding-edge feature id gating the Tier-2 dependent-closure kill oracle (#254).
-      # Same reason as above for naming it here rather than inlining the string.
       DEPENDENT_CLOSURE_KILL_ORACLE = "dependent-closure-kill-oracle"
 
       # #264 — the "loud" threshold for a rescued-harness-failure count. Below it, a rescued mutant reads as
@@ -52,8 +51,7 @@ module Rigor
         MeasurementIntegrityWarning.emit(report, err: @err, floor: HARNESS_ERROR_WARN_FLOOR)
       end
 
-      # The cross-file knowledge Tier 2 measures with — the #253 gate, and the ONLY place in this feature that
-      # knows a feature id exists.
+      # The cross-file knowledge Tier 2 measures with, gated on the #253 feature.
       #
       # Returns nil (today's behaviour: an unseeded per-file view on both halves of the measurement) unless the
       # project has adopted `discovery-seeded-mutation-sites`. With it adopted, returns the table set
@@ -81,7 +79,7 @@ module Rigor
         seed.empty? ? nil : seed
       end
 
-      # The kill oracle Tier 2 measures with — the #254 gate, and the only place that feature id is read.
+      # The kill oracle Tier 2 measures with, gated on the #254 feature.
       #
       # Returns nil (today's behaviour: {Protection::DiagnosticOracle}, which re-analyses the mutated file
       # alone) unless the project has adopted `dependent-closure-kill-oracle`. With it adopted, returns the
@@ -139,7 +137,7 @@ module Rigor
       # warm loop), then re-analyses each target file's mutants against its clean baseline. Defaults to the git-changed
       # `.rb` files; explicit paths override (and enable the whole-project opt-in, which is minutes).
       def run_mutation_protection(options)
-        explicit = collect_paths(@argv, command_name: "coverage")
+        explicit = collect_paths_reporting(@argv)
         return CLI::EXIT_USAGE if explicit.nil?
 
         target_files = explicit.empty? ? changed_ruby_files : explicit
@@ -204,8 +202,8 @@ module Rigor
         determine_protection_exit(report, options)
       end
 
-      # An explicit `--workers=N` on the fused path cannot be honoured, so say so rather than repeat the bug
-      # this slice fixed (a flag accepted and silently dropped). Only the explicit flag warns — a project-wide
+      # An explicit `--workers=N` on the fused path cannot be honoured, so say so rather than drop it silently. Only the
+      # explicit flag warns — a project-wide
       # `parallel.workers:` or `RIGOR_RACTOR_WORKERS` default is not a request about *this* run.
       def warn_workers_ignored_under_tests(options)
         return unless options[:workers].to_i > 1

data/lib/rigor/cli/coverage_renderer.rb

@@ -2,6 +2,7 @@
 
 require "json"
 require_relative "renderable"
+require_relative "json_document"
 
 module Rigor
   class CLI
@@ -93,7 +94,7 @@ module Rigor
       end
 
       def render_json(report)
-        @out.puts(JSON.pretty_generate(json_payload(report)))
+        @out.puts(JSON.pretty_generate(JsonDocument.stamp(json_payload(report), mode: "precision")))
       end
 
       def json_payload(report)

data/lib/rigor/cli/coverage_scan.rb

@@ -23,11 +23,9 @@ module Rigor
 
       # @param files — explicit `.rb` file paths to scan.
       #
-      # Issue #513 — the environment is PLUGIN-AWARE (`LanguageServer::ProjectContext`, the same builder
-      # `--protection` uses), not the bare RBS environment this path carried until 2026-09-01. Without the
-      # plugin registry every plugin-typed receiver read `Dynamic` and the precision ratio understated the
-      # engine by ~1.2 points on a Rails target — the defect the protection path documented and fixed for
-      # itself on 2026-07-04, never applied here.
+      # Issue #513 — the environment is plugin-aware (`LanguageServer::ProjectContext`, the same builder
+      # `--protection` uses). A bare RBS environment read every plugin-typed receiver as `Dynamic` and understated
+      # the precision ratio by ~1.2 points on a Rails target.
       def precision_report(files:, configuration:)
         scope = discovery_seeded_scope(
           files: files,

data/lib/rigor/cli/diff_command.rb

@@ -5,11 +5,12 @@ require_relative "options"
 
 require "json"
 require "optionparser"
+require_relative "json_document"
 
 module Rigor
   class CLI
-    # Executes `rigor diff <baseline.json> [paths...]`. Compares the current `rigor check` diagnostics against a saved
-    # baseline JSON (the output of a previous `rigor check --format=json` run) and prints the delta:
+    # Executes `rigor diff <rigor-check.json> [paths...]`. Compares the current `rigor check` diagnostics against a
+    # saved `rigor check --format=json` result and prints the delta:
     #
     # - **new** — diagnostics in the current run that were not
     #   in the baseline (typically a regression introduced in
@@ -21,11 +22,11 @@ module Rigor
     # diagnostic to a new line surfaces as one fixed + one new pair, which lines up with the user's mental model of "you
     # changed the line, the analyzer's position changed too."
     #
-    # CI usage: commit a `rigor.baseline.json` produced once with `rigor check --format=json > rigor.baseline.json`,
-    # then run `rigor diff rigor.baseline.json` in CI. Exit code is `1` when any new diagnostic appears, `0` otherwise —
+    # CI usage: commit a `rigor-check.json` produced once with `rigor check --format=json > rigor-check.json`, then
+    # run `rigor diff rigor-check.json` in CI. Exit code is `1` when any new diagnostic appears, `0` otherwise —
     # so adding new errors fails CI but legacy errors recorded in the baseline don't.
     class DiffCommand < Command
-      USAGE = "Usage: rigor diff [options] <baseline.json> [paths...]"
+      USAGE = "Usage: rigor diff [options] <rigor-check.json> [paths...]"
 
       # @return CLI exit status.
       def run
@@ -51,22 +52,26 @@ module Rigor
         diff[:new].any? ? 1 : 0
       end
 
-      private
-
-      def parse_options
-        options = { format: "text", current_path: nil, config: nil }
+      # The parser this command parses with, built without parsing anything: the catalogue reads the
+      # flags and formats from it (ADR-126 WD3). `options` is only written by the switches' blocks.
+      def option_parser(options = {})
         OptionParser.new do |opt|
           opt.banner = USAGE
-          opt.on("--format=FORMAT", %w[text json], "Output format (text | json). Default: text.") do |fmt|
-            options[:format] = fmt
-          end
+          Options.add_format(opt, options, "Output format (text | json). Default: text.")
           opt.on("--current=PATH", "Compare to the saved current JSON instead of running `rigor check`.") do |path|
             options[:current_path] = path
           end
           opt.on("--config=PATH", "Path to .rigor.yml. Forwarded to the implicit `rigor check` run.") do |path|
             options[:config] = Options.config_path(path)
           end
-        end.parse!(@argv)
+        end
+      end
+
+      private
+
+      def parse_options
+        options = { format: "text", current_path: nil, config: nil }
+        option_parser(options).parse!(@argv)
         options
       end
 
@@ -121,13 +126,13 @@ module Rigor
       end
 
       def write_diff_json(diff, baseline_path, baseline_count, current_count)
-        @out.puts(JSON.pretty_generate(
-                    "baseline" => baseline_path,
-                    "baseline_count" => baseline_count,
-                    "current_count" => current_count,
-                    "new" => diff[:new],
-                    "fixed" => diff[:fixed]
-                  ))
+        @out.puts(JSON.pretty_generate(JsonDocument.stamp({
+                                                            "baseline" => baseline_path,
+                                                            "baseline_count" => baseline_count,
+                                                            "current_count" => current_count,
+                                                            "new" => diff[:new],
+                                                            "fixed" => diff[:fixed]
+                                                          })))
       end
 
       def write_diff_text(diff, baseline_path, baseline_count, current_count)

data/lib/rigor/cli/docs_command.rb

@@ -203,8 +203,7 @@ module Rigor
           relative: relative,
           path: path,
           category: category,
-          # Always-unique addresses: the `docs/`-relative path and the prefixed basename. `handbook/03-narrowing` and
-          # `03-narrowing`.
+          # Always-unique addresses: the `docs/`-relative path and the prefixed basename.
           exact_aliases: [relative, base].uniq,
           # The prefix-stripped short name (`narrowing`); ambiguous when two categories carry the same chapter slug
           # (`plugins`).

data/lib/rigor/cli/doctor_command.rb

@@ -17,6 +17,7 @@ require_relative "../type/combinator"
 require_relative "check_invocation"
 require_relative "command"
 require_relative "options"
+require_relative "json_document"
 
 module Rigor
   class CLI
@@ -86,23 +87,22 @@ module Rigor
         CLI::EXIT_USAGE
       end
 
-      private
-
-      def parse_options
-        options = { config: nil, format: "text" }
+      # The parser this command parses with, built without parsing anything: the catalogue reads the
+      # flags and formats from it (ADR-126 WD3). `options` is only written by the switches' blocks.
+      def option_parser(options = {})
         OptionParser.new do |opts|
           opts.banner = USAGE
           Options.add_config(opts, options)
-          opts.on("--format=FORMAT", "Output format: text (default) or json") { |v| options[:format] = v }
-        end.parse!(@argv)
-        validate!(options)
-        options
+          Options.add_format(opts, options, "Output format: text (default) or json")
+        end
       end
 
-      def validate!(options)
-        return if %w[text json].include?(options.fetch(:format))
+      private
 
-        raise OptionParser::InvalidArgument, "unsupported format: #{options.fetch(:format)}"
+      def parse_options
+        options = { config: nil, format: "text" }
+        option_parser(options).parse!(@argv)
+        options
       end
 
       # ------------------------------------------------------------------
@@ -437,7 +437,7 @@ module Rigor
             }
           end
         }
-        @out.puts(JSON.pretty_generate(payload))
+        @out.puts(JSON.pretty_generate(JsonDocument.stamp(payload)))
       end
 
       def report_text(findings)

data/lib/rigor/cli/effects_command.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "did_you_mean"
 require "optionparser"
 
 require_relative "../configuration"
@@ -50,6 +51,38 @@ module Rigor
         run_report
       end
 
+      # The parser this command parses with, built without parsing anything: the catalogue reads the
+      # flags and formats from it (ADR-126 WD3). `options` is only written by the switches' blocks.
+      def option_parser(options = {})
+        OptionParser.new do |opts|
+          opts.banner = USAGE
+          Options.add_config(opts, options)
+          Options.add_format(opts, options, "Output format: text (default) or json")
+          opts.on("--full", "List every method, including the ones with nothing to say") do
+            options[:full] = true
+          end
+          opts.on("--label=LABEL", "Only methods carrying LABEL (or a label under it), in either lane") do |value|
+            options[:label].concat(value.split(",").map(&:strip).reject(&:empty?))
+          end
+          opts.on("--pure", "Only methods proven to do nothing beyond mutate.local — the %a{pure} set") do
+            options[:pure] = true
+          end
+          opts.on("--limit=N", Integer, "Print at most N methods") { |value| options[:limit] = value }
+          opts.on("--why", "Expand each method's unresolved reasons and declared-lane sources") do
+            options[:why] = true
+          end
+          opts.on("--list-labels", "Print the effect vocabulary this project can name, and exit") do
+            options[:list_labels] = true
+          end
+          # Accepted here and deliberately inert, exactly as it is on `update`: the report is an
+          # observation, and observations are undischarged. Only a JUDGMENT reads `effects.tolerated:` —
+          # `rigor effects check` / `diff`, and `rigor check`'s envelope contract.
+          opts.on("--no-tolerated-effects", "Judge as if effects.tolerated: were empty (inert on the report)") do
+            options[:no_tolerated] = true
+          end
+        end
+      end
+
       private
 
       def run_verb(verb)
@@ -91,7 +124,7 @@ module Rigor
 
       def run_report
         options = parse_options
-        return usage_error("unsupported format: #{options.fetch(:format)}") unless FORMATS.include?(options[:format])
+        return CLI::EXIT_USAGE if misspelled_verb?
 
         configuration = Configuration.load(options.fetch(:config)).with_effects_enabled
         return list_labels(configuration) if options.fetch(:list_labels)
@@ -107,6 +140,20 @@ module Rigor
         0
       end
 
+      # A first word that is no path but is one edit from a snapshot verb (`rigor effects updat`) is a misspelled verb,
+      # not a scope: the report would otherwise run to completion and say only that no unit lives in `updat`.
+      def misspelled_verb?
+        word = @argv.first
+        return false if word.nil? || word.match?(%r{[/.]}) || File.exist?(word)
+
+        nearest = ::DidYouMean::SpellChecker.new(dictionary: EffectsSnapshotCommand::VERBS).correct(word).first
+        return false unless nearest
+
+        @err.puts("rigor: unknown effects subcommand: #{word}")
+        @err.puts("Did you mean `rigor effects #{nearest}`?")
+        true
+      end
+
       # A path argument is a **view**, and the note says so (#439).
       #
       # It used to narrow the analysed set, and effect labels are transitive over whatever was analysed —
@@ -131,48 +178,13 @@ module Rigor
                   "label is the one the whole-project run reports")
       end
 
-      FORMATS = %w[text json].freeze
-      private_constant :FORMATS
-
       def parse_options
         options = { config: nil, format: "text", full: false, no_tolerated: false, label: [], pure: false,
                     limit: nil, why: false, list_labels: false }
-        OptionParser.new do |opts|
-          opts.banner = USAGE
-          Options.add_config(opts, options)
-          opts.on("--format=FORMAT", "Output format: text (default) or json") { |value| options[:format] = value }
-          opts.on("--full", "List every method, including the ones with nothing to say") do
-            options[:full] = true
-          end
-          opts.on("--label=LABEL", "Only methods carrying LABEL (or a label under it), in either lane") do |value|
-            options[:label].concat(value.split(",").map(&:strip).reject(&:empty?))
-          end
-          opts.on("--pure", "Only methods proven to do nothing beyond mutate.local — the %a{pure} set") do
-            options[:pure] = true
-          end
-          opts.on("--limit=N", Integer, "Print at most N methods") { |value| options[:limit] = value }
-          opts.on("--why", "Expand each method's unresolved reasons and declared-lane sources") do
-            options[:why] = true
-          end
-          opts.on("--list-labels", "Print the effect vocabulary this project can name, and exit") do
-            options[:list_labels] = true
-          end
-          # Accepted here and deliberately inert, exactly as it is on `update`: the report is an
-          # observation, and observations are undischarged. Only a JUDGMENT reads `effects.tolerated:` —
-          # `rigor effects check` / `diff`, and `rigor check`'s envelope contract.
-          opts.on("--no-tolerated-effects", "Judge as if effects.tolerated: were empty (inert on the report)") do
-            options[:no_tolerated] = true
-          end
-        end.parse!(@argv)
+        option_parser(options).parse!(@argv)
         options
       end
 
-      def usage_error(message)
-        @err.puts(message)
-        @err.puts(USAGE)
-        CLI::EXIT_USAGE
-      end
-
       # Sequential and cache-backed, through the same ADR-45 whole-run result cache `rigor check` uses:
       # the diagnostics entry serves the run and the #382 effects sidecar serves the collections, leaving
       # only the fixpoint. Sequential is not a cache decision — the run-result cache declines pool mode —
@@ -222,9 +234,7 @@ module Rigor
 
       # The analysed set is the configured `paths:` **plus** whatever the arguments name — never the
       # arguments alone (#439). An effect summary is transitive over whatever was analysed, so analysing
-      # less does not filter the report, it lowers every answer in it: `rigor effects
-      # app/controllers/issues_controller.rb` used to report `IssuesController#create: [] …?` where the
-      # whole-project run reported four labels and a declared lane, with nothing marking the difference.
+      # less does not filter the report, it lowers every answer in it.
       #
       # The union rather than the configured paths alone, so that pointing the command at a tree the
       # configuration does not cover — which is what every `rigor effects PATH` invocation from outside a

data/lib/rigor/cli/effects_diff_renderer.rb

@@ -6,6 +6,7 @@ require_relative "../effects/definition_lines"
 require_relative "../effects/snapshot"
 require_relative "../effects/snapshot_diff"
 require_relative "renderable"
+require_relative "json_document"
 
 module Rigor
   class CLI
@@ -121,7 +122,7 @@ module Rigor
       # method that no longer exists was not defined by it. Such a row renders exactly as it did before
       # this suffix existed.
       #
-      # @return `[relative path, line]` per file, the line nil when that
+      # @return a relative path and line per file, the line nil when that
       #   file spells the key with no `def` — an accessor, or a definition the nesting cannot name.
       def sources_of(symbol)
         Array(@sources[symbol]).map do |path|
@@ -175,22 +176,22 @@ module Rigor
       end
 
       def render_json(diff)
-        @out.puts(JSON.pretty_generate(
-                    "fresh" => diff.fresh?,
-                    "events" => diff.events.map { |event| event_json(event) },
-                    "footer" => {
-                      "added_symbols" => diff.footer[:added_symbols],
-                      "removed_symbols" => diff.footer[:removed_symbols],
-                      "suppressed" => diff.footer[:suppressed]
-                    },
-                    "regeneration" => diff.regeneration?,
-                    "header" => {
-                      "snapshot" => @path,
-                      "gate" => diff.gate.to_s,
-                      "recorded" => diff.recorded&.header,
-                      "current" => diff.current.header
-                    }
-                  ))
+        @out.puts(JSON.pretty_generate(JsonDocument.stamp({
+                                                            "fresh" => diff.fresh?,
+                                                            "events" => diff.events.map { |event| event_json(event) },
+                                                            "footer" => {
+                                                              "added_symbols" => diff.footer[:added_symbols],
+                                                              "removed_symbols" => diff.footer[:removed_symbols],
+                                                              "suppressed" => diff.footer[:suppressed]
+                                                            },
+                                                            "regeneration" => diff.regeneration?,
+                                                            "header" => {
+                                                              "snapshot" => @path,
+                                                              "gate" => diff.gate.to_s,
+                                                              "recorded" => diff.recorded&.header,
+                                                              "current" => diff.current.header
+                                                            }
+                                                          })))
       end
     end
   end

data/lib/rigor/cli/effects_explain_renderer.rb

@@ -3,6 +3,7 @@
 require "json"
 
 require_relative "renderable"
+require_relative "json_document"
 
 module Rigor
   class CLI
@@ -53,18 +54,18 @@ module Rigor
       end
 
       def render_json(rows)
-        @out.puts(JSON.pretty_generate(
-                    "paths" => rows.map do |row|
-                      {
-                        "table" => row.table,
-                        "symbol" => row.symbol,
-                        "label" => row.label,
-                        "path" => row.path,
-                        "origin" => row.origin,
-                        "causes" => row.causes
-                      }
-                    end
-                  ))
+        @out.puts(JSON.pretty_generate(JsonDocument.stamp({
+                                                            "paths" => rows.map do |row|
+                                                              {
+                                                                "table" => row.table,
+                                                                "symbol" => row.symbol,
+                                                                "label" => row.label,
+                                                                "path" => row.path,
+                                                                "origin" => row.origin,
+                                                                "causes" => row.causes
+                                                              }
+                                                            end
+                                                          })))
       end
     end
   end

data/lib/rigor/cli/effects_renderer.rb

@@ -3,6 +3,7 @@
 require "json"
 
 require_relative "renderable"
+require_relative "json_document"
 
 module Rigor
   class CLI
@@ -85,7 +86,7 @@ module Rigor
           end
         }
         payload["totals"] = report.totals.to_h.transform_keys(&:to_s) if report.totals
-        @out.puts(JSON.pretty_generate(payload))
+        @out.puts(JSON.pretty_generate(JsonDocument.stamp(payload)))
       end
     end
   end

data/lib/rigor/cli/effects_snapshot_command.rb

@@ -38,9 +38,6 @@ module Rigor
     class EffectsSnapshotCommand < Command
       VERBS = %w[update check diff explain].freeze
 
-      FORMATS = %w[text json].freeze
-      private_constant :FORMATS
-
       # The verbs that read a committed record, and so accept `--baseline PATH` —
       # `--baseline <(git show origin/main:.rigor-effects.yml)` is the bot form.
       COMPARING_VERBS = %w[check diff explain].freeze
@@ -54,8 +51,6 @@ module Rigor
       # @return 0 fresh / written, 1 on drift under `check`, 64 on a usage error.
       def run
         options = parse_options
-        return usage_error("unsupported format: #{options.fetch(:format)}") unless
-          FORMATS.include?(options[:format])
         return usage_error("rigor effects #{@verb} takes no paths; it records the configured paths:") unless
           @argv.empty?
 
@@ -64,6 +59,22 @@ module Rigor
         usage_error(e.message)
       end
 
+      # The parser this command parses with, built without parsing anything: the catalogue reads the
+      # flags and formats from it (ADR-126 WD3). `options` is only written by the switches' blocks.
+      def option_parser(options = {})
+        OptionParser.new do |opts|
+          opts.banner = "Usage: rigor effects #{@verb} [options]"
+          Options.add_config(opts, options)
+          add_common_options(opts, options)
+          add_comparison_options(opts, options) if COMPARING_VERBS.include?(@verb)
+          if @verb == "explain"
+            opts.on("--symbol=KEY", "Explain this unit instead of the changed ones") do |value|
+              options[:symbol] = value
+            end
+          end
+        end
+      end
+
       private
 
       def execute(options)
@@ -80,7 +91,14 @@ module Rigor
       # exists" hazard: it records observations, so overwriting it is the whole point of running it.
       def write(configuration, snapshot)
         path = configuration.effects_snapshot_path
-        File.write(path, snapshot.to_yaml)
+        begin
+          File.write(path, snapshot.to_yaml)
+        rescue SystemCallError => e
+          # #2576 — an `effects.snapshot.path:` that cannot be written is a usage error, the same rule
+          # `rigor init --path` follows (#2562): one line on stderr and exit 64, no backtrace.
+          @err.puts("rigor effects: cannot write #{path}: #{e.message.sub(/ @ .*\z/m, '')}")
+          return CLI::EXIT_USAGE
+        end
         @err.puts("rigor: wrote #{path} (#{snapshot.methods.size} method(s), #{snapshot.reach.size} reach entr" \
                   "#{snapshot.reach.size == 1 ? 'y' : 'ies'})")
         # #436 — the note names what to write, not only what is missing: the same per-project preset
@@ -273,17 +291,7 @@ module Rigor
       def parse_options
         options = { config: nil, format: "text", full: false, baseline: nil, symbol: nil,
                     strict_tolerated: false, no_tolerated: false }
-        OptionParser.new do |opts|
-          opts.banner = "Usage: rigor effects #{@verb} [options]"
-          Options.add_config(opts, options)
-          add_common_options(opts, options)
-          add_comparison_options(opts, options) if COMPARING_VERBS.include?(@verb)
-          if @verb == "explain"
-            opts.on("--symbol=KEY", "Explain this unit instead of the changed ones") do |value|
-              options[:symbol] = value
-            end
-          end
-        end.parse!(@argv)
+        option_parser(options).parse!(@argv)
         options
       end
 
@@ -292,7 +300,7 @@ module Rigor
       # byte-identical files. A flag that changed the record would make the file a function of policy and
       # a policy change indistinguishable from a code change.
       def add_common_options(opts, options)
-        opts.on("--format=FORMAT", "Output format: text (default) or json") { |value| options[:format] = value }
+        Options.add_format(opts, options, "Output format: text (default) or json")
         opts.on("--full", "Record every method, including the omitted trivial and synthesised ones") do
           options[:full] = true
         end