rigortype 0.4.6 → 0.4.7

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)
@@ -273,17 +284,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 +293,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

data/lib/rigor/cli/explain_command.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "json"
+require_relative "json_document"
 require "optionparser"
 
 require_relative "../analysis/rule_catalog"
@@ -46,22 +47,28 @@ module Rigor
         0
       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 |opt|
+          opt.banner = USAGE
+          Options.add_format(opt, options, "Output format (text | json). Default: text.")
+        end
+      end
+
       private
 
       def parse_options
         options = { format: "text" }
-        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
-        end.parse!(@argv)
+        option_parser(options).parse!(@argv)
         options
       end
 
       def render_index(format)
         case format
-        when "json" then @out.puts(JSON.pretty_generate(Analysis::RuleCatalog.all.map(&:to_h)))
+        when "json"
+          @out.puts(JSON.pretty_generate(Analysis::RuleCatalog.all.map(&:to_h)))
+          @err.puts(JsonDocument::SHAPE_NOTICES.fetch(:explain_rules))
         else render_index_text
         end
       end
@@ -87,6 +94,7 @@ module Rigor
       def render_skip_reason(entry, format)
         if format == "json"
           @out.puts(JSON.pretty_generate(entry.to_h))
+          @err.puts(JsonDocument::SHAPE_NOTICES.fetch(:explain_skip_reasons))
           return
         end
 
@@ -106,7 +114,9 @@ module Rigor
 
       def render_entries(entries, format)
         case format
-        when "json" then @out.puts(JSON.pretty_generate(entries.map(&:to_h)))
+        when "json"
+          @out.puts(JSON.pretty_generate(entries.map(&:to_h)))
+          @err.puts(JsonDocument::SHAPE_NOTICES.fetch(:explain_rules))
         else
           entries.each_with_index do |entry, index|
             @out.puts("") if index.positive?

data/lib/rigor/cli/fused_protection_renderer.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "json"
+require_relative "json_document"
 
 module Rigor
   class CLI
@@ -23,7 +24,7 @@ module Rigor
       private
 
       def render_json(report)
-        @out.puts(JSON.pretty_generate(report.to_h))
+        @out.puts(JSON.pretty_generate(JsonDocument.stamp(report.to_h)))
       end
 
       def render_text(report)

data/lib/rigor/cli/json_document.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Rigor
+  class CLI
+    # The version marker every `--format=json` document Rigor defines carries (ADR-126 WD2, ADR-50 WD1).
+    #
+    # `schema_version` is the first top-level key and counts per document (per `mode` where a flag selects a
+    # different document). Adding a key keeps the version; removing or renaming one is a major-only change at
+    # v1.0.0. `lens` (`schema`/`revision`), `baseline dump` (`version`) and `check`'s external formats keep
+    # their own markers and do not pass through here.
+    module JsonDocument
+      SCHEMA_VERSION = 1
+
+      # @param payload — the document's top-level object (string or symbol keys).
+      # @param mode — names the document when a flag selects among several; nil when the command has one.
+      # @return a new Hash whose first key is `schema_version` (then `mode`, when given).
+      def self.stamp(payload, mode: nil)
+        head = { "schema_version" => SCHEMA_VERSION }
+        head["mode"] = mode if mode
+        head.merge(payload)
+      end
+
+      # The one-line stderr notice for `type-of`, `explain` and `trace`, whose top-level JSON shape changes in
+      # the next minor (ADR-126 WD4). stdout stays byte-identical until then. The MCP server appends the same
+      # text as its own content block, recognised by {NOTICE_PATTERN}.
+      def self.shape_notice(command, replacement)
+        "rigor: note — `rigor #{command} --format=json` will print #{replacement} from the next minor " \
+          "release (currently a different top-level shape); update JSON consumers now. See ADR-126."
+      end
+
+      NOTICE_PATTERN = /^rigor: note — `rigor [a-z-]+ --format=json` will print .*$/
+
+      SHAPE_NOTICES = {
+        type_of: shape_notice("type-of", '{ "schema_version": 1, "results": [...] }').freeze,
+        trace: shape_notice("trace", '{ "schema_version": 1, "events": [...] }').freeze,
+        explain_rules: shape_notice("explain", '{ "schema_version": 1, "rules": [...] }').freeze,
+        explain_skip_reasons: shape_notice("explain", '{ "schema_version": 1, "skip_reasons": [...] }').freeze
+      }.freeze
+    end
+  end
+end

data/lib/rigor/cli/lens_command.rb

@@ -15,7 +15,6 @@ module Rigor
     # computes them (ADR-113; output contract docs/internal-spec/lens.md). Experimental until `lens/v1`.
     class LensCommand < Command
       USAGE = "Usage: rigor lens [--format=text|json] [--config=PATH] [--workers=N] FILE..."
-      FORMATS = %w[text json].freeze
 
       def run
         options = parse_options
@@ -35,17 +34,22 @@ module Rigor
         outcome.targets.any? { |target| target.status == "ok" } ? 0 : 1
       end
 
-      private
-
-      def parse_options
-        options = { format: "text", config: nil, workers: 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 |opts|
           opts.banner = USAGE
-          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("--workers=N", Integer, "Worker processes for a cold run") { |value| options[:workers] = value }
           Options.add_config(opts, options)
-        end.parse!(@argv)
-        return usage_error("--format must be text or json") unless FORMATS.include?(options[:format])
+        end
+      end
+
+      private
+
+      def parse_options
+        options = { format: "text", config: nil, workers: nil }
+        option_parser(options).parse!(@argv)
         return usage_error("no FILE given") if @argv.empty?
 
         options