rigortype 0.4.5 → 0.4.7

data/lib/rigor/cli/options.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "../analysis/buffer_binding"
+require_relative "../configuration_error"
 
 module Rigor
   class CLI
@@ -10,37 +11,92 @@ module Rigor
     # `--instead-of` flag pair and the buffer-binding resolution that validates it. That resolution used to be copied
     # verbatim into both `Rigor::CLI` and `TypeOfCommand`, so a fix to one (the paired-flag check, the readability
     # check, the error wording) could silently miss the other. Centralising it keeps the two editor-mode entry points in
-    # lockstep.
+    # lockstep. It also owns the `--config` check (#1992), so every command and the MCP tools that pass `--config`
+    # read the same rule.
     module Options
       module_function
 
+      # The formats `parser` accepts for `--format`, or nil when {.add_format} did not define the switch. A
+      # block-validated switch carries no list of its own, so {.add_format} leaves it on the parser for the CLI
+      # catalogue (ADR-126 WD3) to read.
+      def accepted_formats(parser)
+        parser.instance_variable_get(:@rigor_accepted_formats)
+      end
+
       # Defines the standard `--config=PATH` flag on `parser`, writing the path into `options[:config]`. Used by every
       # subcommand that loads a `.rigor.yml`; the few whose `--config` help text is intentionally bespoke (`diff`,
-      # `mcp`, `show-bleedingedge`) keep their own `parser.on` rather than this shared wording.
+      # `mcp`, `show-bleedingedge`) keep their own `parser.on` and call {.config_path} for the same check.
       def add_config(parser, options)
-        parser.on("--config=PATH", "Path to the Rigor configuration file") { |value| options[:config] = value }
+        parser.on("--config=PATH", "Path to the Rigor configuration file") do |value|
+          options[:config] = config_path(value)
+        end
+      end
+
+      # Defines `--format=FORMAT` restricted to `formats`, so an unsupported value is an `OptionParser::InvalidArgument`
+      # raised while the options are parsed (#2502). A check left to the renderer ran the whole analysis first, and a
+      # renderer that read only `format == "json"` printed text for any other value. The match is exact: an
+      # OptionParser enum would also complete a prefix (`--format=j`), which then turns ambiguous the day a second
+      # format shares it. The renderers' own "unsupported format" branches remain as a guard against internal drift.
+      def add_format(parser, options, description, formats: %w[text json])
+        parser.instance_variable_set(:@rigor_accepted_formats, formats.dup.freeze)
+        parser.on("--format=FORMAT", description) do |value|
+          raise OptionParser::InvalidArgument, value unless formats.include?(value)
+
+          options[:format] = value
+        end
+      end
+
+      # The `--config` value, checked where the flag is read (#1992). A named file that is not there is an error, not
+      # a request for the defaults: the run would otherwise analyse under a configuration the caller did not ask for,
+      # and an MCP caller would get a result for it with no sign anything was missing. Auto-discovery, with no
+      # `--config` given, is not affected.
+      def config_path(value)
+        raise ConfigurationError, "empty config path" if value.strip.empty?
+        raise ConfigurationError, "config path is a directory: #{value}" if File.directory?(value)
+        raise ConfigurationError, "config file not found: #{value}" unless File.exist?(value)
+        raise ConfigurationError, "config file not readable: #{value}" unless File.readable?(value)
+
+        value
       end
 
       # Defines the `--tmp-file` / `--instead-of` editor-mode flag pair on `parser`, writing into `options`.
       def add_editor_mode(parser, options)
         parser.on("--tmp-file=PATH",
                   "Editor mode: read source bytes from PATH instead of --instead-of (paired)") do |value|
+          note_repeated_editor_flag(options, :tmp_file, "--tmp-file")
           options[:tmp_file] = value
         end
         parser.on("--instead-of=PATH",
                   "Editor mode: the logical project path the buffer represents (paired with --tmp-file)") do |value|
+          note_repeated_editor_flag(options, :instead_of, "--instead-of")
           options[:instead_of] = value
         end
       end
 
+      # Issue #2233 — editor mode binds one buffer per run, so a second `--tmp-file` or `--instead-of` cannot be
+      # honoured beside the first. Overwriting it dropped the first pair with no message; the repeat is recorded here
+      # and rejected by {resolve_buffer_binding} as a usage error instead.
+      def note_repeated_editor_flag(options, key, flag)
+        return if options[key].nil?
+
+        (options[:repeated_editor_flags] ||= []) << flag
+      end
+
       # Resolves the editor-mode buffer binding from parsed `options`: returns nil when neither editor-mode flag is set,
       # a `Analysis::BufferBinding` when the pair is valid, or `:usage_error` (after writing the reason to `err`) when
-      # the flags are unpaired or the temp file is unreadable.
+      # a flag is repeated, the flags are unpaired, or the temp file is unreadable.
       def resolve_buffer_binding(options, err:)
         tmp = options[:tmp_file]
         instead = options[:instead_of]
         return nil if tmp.nil? && instead.nil?
 
+        repeated = Array(options[:repeated_editor_flags])
+        unless repeated.empty?
+          err.puts("#{repeated.join(' and ')} given more than once; editor mode takes one buffer per run " \
+                   "(a single --tmp-file / --instead-of pair)")
+          return :usage_error
+        end
+
         if tmp.nil? || instead.nil?
           err.puts("--tmp-file and --instead-of must appear together")
           return :usage_error

data/lib/rigor/cli/plugin_command.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "optparse"
+
 require_relative "command"
 require_relative "../rooted_glob"
 
@@ -7,7 +9,7 @@ module Rigor
   class CLI
     # `rigor plugin` (singular) — discover and read the plugin source bundled with the `rigortype` gem.
     #
-    # Rigor ships ~30 production plugins under `plugins/` and a set of tutorial plugins under `examples/`. When Rigor is
+    # Rigor ships production plugins under `plugins/` and tutorial plugins under `examples/`. When Rigor is
     # installed via `mise` / `gem install` the gem checkout is on disk, so a plugin author (or an AI coding agent
     # following the `rigor-plugin-author` skill) can read a real, working plugin as a worked example — instead of
     # guessing the `Rigor::Plugin::Base` surface from prose. This command outputs the absolute paths so they can be
@@ -17,75 +19,122 @@ module Rigor
     # configured in *your* `.rigor.yml`. This command (singular) browses the plugins bundled in the *toolchain*.
     # Mnemonic: "plugins" = my config; "plugin" = the catalogue I can learn from.
     #
-    # Subcommands:
+    # Grammar (mirrors `rigor docs` and `rigor skill`, ADR-126 WD4): the positional slot is always a plugin *name*;
+    # alternative outputs are flags, so a plugin can never be shadowed by a verb.
     #
-    # - `rigor plugin list`          — every bundled plugin + example,
-    #                                  name + absolute directory path.
-    # - `rigor plugin path <name>`   — one-line absolute path to the
-    #                                  plugin's directory (Read-tool input).
-    # - `rigor plugin print <name>`  — a header (dir / lib / sig / README
-    #                                  paths) followed by the plugin's main
+    # - `rigor plugin`               — every bundled plugin + example, name + absolute directory path (the default).
+    # - `rigor plugin <name>`        — a header (dir / lib / sig / README paths) followed by the plugin's main
     #                                  `lib/<name>.rb` source body.
-    # - `rigor plugin root`          — the rigortype gem root and its key
-    #                                  subdirectories (lib/, plugins/,
-    #                                  examples/, skills/, sig/), so an
-    #                                  author can read the public plugin
-    #                                  API (`lib/rigor/plugin.rb`) directly.
+    # - `rigor plugin --path <name>` — one-line absolute path to the plugin's directory (Read-tool input).
+    # - `rigor plugin --list`        — the same listing as no argument.
+    # - `rigor plugin --root`        — the rigortype gem root and its key subdirectories (lib/, plugins/, examples/,
+    #                                  skills/, sig/), so an author can read the public plugin API
+    #                                  (`lib/rigor/plugin.rb`) directly.
     #
-    # `rigor plugin` with no subcommand is an alias for `list`.
+    # The verbs `list`, `path <name>`, `print <name>` and `root` are the pre-ADR-126 spelling. They still work for one
+    # minor, print the same stdout and return the same status, and add one deprecation notice on stderr naming the
+    # replacement.
     #
     # **Docker / cross-filesystem note.** Every path printed is resolved at runtime from this file's location, so it is
     # correct *on the filesystem where `rigor` runs*. If you run `rigor` inside a container but read files from the host
     # (or vice versa), the paths will not resolve — read them from the same environment that ran the command (`rigor
-    # plugin print` inlines the body for exactly this case: it works with no file-reading tool at all).
+    # plugin <name>` inlines the body for exactly this case: it works with no file-reading tool at all).
     class PluginCommand < Command
       USAGE = <<~USAGE
-        Usage: rigor plugin <subcommand> [args]
+        Usage: rigor plugin [<name>] [--path <name>] [--list] [--root]
 
         Browse the plugins bundled in the rigortype toolchain (worked
         examples for authoring your own). For the activation status of
         the plugins in your .rigor.yml, use `rigor plugins` (plural).
 
-        Subcommands:
-          list                  List bundled + example plugins (default)
-          path  <name>          Print the absolute directory path of <name>
-          print <name>          Print <name>'s main lib source, with a header
-          root                  Print the gem root + key subdirectories
+          rigor plugin                List bundled + example plugins
+          rigor plugin <name>         Print <name>'s main lib source, with a header
+          rigor plugin --path <name>  Print the absolute directory path of <name>
+          rigor plugin --list         List bundled + example plugins
+          rigor plugin --root         Print the gem root + key subdirectories
 
         Examples:
-          rigor plugin list
-          rigor plugin path  rigor-activerecord
-          rigor plugin print rigor-activesupport-core-ext
-          rigor plugin root
+          rigor plugin
+          rigor plugin rigor-activesupport-core-ext
+          rigor plugin --path rigor-activerecord
+          rigor plugin --root
       USAGE
 
+      # The pre-ADR-126 verbs, each with the spelling that replaces it.
+      DEPRECATED_VERBS = {
+        "list" => "rigor plugin --list",
+        "path" => "rigor plugin --path <name>",
+        "print" => "rigor plugin <name>",
+        "root" => "rigor plugin --root"
+      }.freeze
+
       # The bundled plugins/examples/source live at `<gem_root>/...`. From `lib/rigor/cli/plugin_command.rb` the gem
       # root is three directories up (matching SkillCommand::SKILLS_ROOT).
       GEM_ROOT     = File.expand_path("../../..", __dir__).freeze
       PLUGINS_ROOT = File.join(GEM_ROOT, "plugins").freeze
       EXAMPLES_ROOT = File.join(GEM_ROOT, "examples").freeze
 
+      # The parser this command parses with, built without parsing anything: the catalogue reads its flags from it
+      # (ADR-126 WD3). `options` is only written by the switches' blocks.
+      def option_parser(options = {})
+        OptionParser.new do |opts|
+          opts.banner = USAGE.lines.first.chomp
+          opts.on("--path NAME", "Print the absolute directory path of a plugin") { |value| options[:path] = value }
+          opts.on("--list", "List bundled + example plugins") { options[:list] = true }
+          opts.on("--root", "Print the gem root + key subdirectories") { options[:root] = true }
+        end
+      end
+
       # @return CLI exit status.
       def run
-        subcommand = @argv.shift || "list"
-
-        case subcommand
-        when "list" then run_list
-        when "path" then run_path
-        when "print" then run_print
-        when "root" then run_root
-        when "-h", "--help", "help"
+        if @argv.intersect?(%w[-h --help])
           @out.puts(USAGE)
-          0
-        else
-          @err.puts("Unknown subcommand: #{subcommand}")
-          @err.puts(USAGE)
-          Rigor::CLI::EXIT_USAGE
+          return 0
         end
+
+        verb = @argv.first
+        return run_deprecated_verb(@argv.shift) if DEPRECATED_VERBS.key?(verb)
+        return run_help if verb == "help"
+
+        run_grammar
       end
 
       private
 
+      def run_help
+        @out.puts(USAGE)
+        0
+      end
+
+      def run_grammar
+        options = {}
+        begin
+          option_parser(options).parse!(@argv)
+        rescue OptionParser::ParseError => e
+          return usage_error(e.message)
+        end
+        return run_path(options[:path]) if options.key?(:path)
+        return run_root if options[:root]
+        return run_list if options[:list]
+
+        name = @argv.shift
+        name.nil? ? run_list : run_print(name)
+      end
+
+      def run_deprecated_verb(verb)
+        @err.puts("rigor: `rigor plugin #{verb}` is deprecated and will be removed in the next minor release; " \
+                  "use `#{DEPRECATED_VERBS.fetch(verb)}`.")
+        # The verbs' stdout stays byte-identical to what they printed before the grammar changed, so its prose still
+        # names the verb spelling.
+        @legacy = true
+        case verb
+        when "list" then run_list
+        when "path" then run_path(@argv.shift)
+        when "print" then run_print(@argv.shift)
+        else run_root
+        end
+      end
+
       def run_list
         plugins = discover(PLUGINS_ROOT)
         examples = discover(EXAMPLES_ROOT)
@@ -113,8 +162,7 @@ module Rigor
         end
       end
 
-      def run_path
-        name = @argv.shift
+      def run_path(name)
         return usage_error("`path` requires a plugin name") if name.nil?
 
         plugin = find(name)
@@ -124,8 +172,7 @@ module Rigor
         0
       end
 
-      def run_print
-        name = @argv.shift
+      def run_print(name)
         return usage_error("`print` requires a plugin name") if name.nil?
 
         plugin = find(name)
@@ -159,7 +206,7 @@ module Rigor
         0
       end
 
-      # The header that precedes the plugin body when an author runs `rigor plugin print <name>`. `# `-prefixed so the
+      # The header that precedes the plugin body when an author runs `rigor plugin <name>`. `# `-prefixed so the
       # combined output stays readable; the Ruby body below it is unchanged.
       def render_print_header(plugin)
         dir = plugin.fetch(:path)
@@ -176,7 +223,7 @@ module Rigor
           # The main source body is below; read the other files from the
           # paths above. To suppress `call.undefined-method` for methods a
           # DSL generates, study how an RBS-bundle plugin ships `sig/` (see
-          # `rigor plugin print rigor-activesupport-core-ext`).
+          # `#{@legacy ? 'rigor plugin print' : 'rigor plugin'} rigor-activesupport-core-ext`).
         HEADER
       end
 
@@ -211,12 +258,12 @@ module Rigor
       def docker_note
         "\nNote: paths are local to where `rigor` runs. If you run rigor in a " \
           "container,\nread these files from the same filesystem (use " \
-          "`rigor plugin print` to inline a body)."
+          "`#{@legacy ? 'rigor plugin print' : 'rigor plugin <name>'}` to inline a body)."
       end
 
       def name_error(name)
         @err.puts("Unknown plugin: #{name}")
-        @err.puts("Run `rigor plugin list` to see the bundled plugins.")
+        @err.puts("Run `rigor plugin --list` to see the bundled plugins.")
         1
       end
 

data/lib/rigor/cli/plugins_command.rb

@@ -30,7 +30,7 @@ module Rigor
     # - every manifest-declared extension surface
     #   (`open_receivers:` / `owns_receivers:` / `produces:` /
     #   `consumes:` / `block_as_methods:` / `heredoc_templates:` /
-    #   `trait_registries:` /
+    #   `trait_registries:` / `per_invocation_classes:` /
     #   `type_node_resolvers:` / `hkt_registrations:` /
     #   `hkt_definitions:` / `protocol_contracts:` /
     #   `source_rbs_synthesizer:`);
@@ -80,6 +80,20 @@ 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 |opts|
+          opts.banner = USAGE
+          Options.add_config(opts, options)
+          Options.add_format(opts, options, "Output format: text (default) or json")
+          opts.on("--strict", "Exit 1 if any plugin failed to load (CI gate)") { options[:strict] = true }
+          opts.on("--capabilities", "Emit the per-plugin extension-protocol catalogue (ADR-37)") do
+            options[:capabilities] = true
+          end
+        end
+      end
+
       private
 
       # Picks the renderer view. `--capabilities` switches to the focused extension-protocol catalogue (ADR-37 §
@@ -97,25 +111,10 @@ module Rigor
 
       def parse_options
         options = { config: nil, format: "text", strict: false, capabilities: false }
-        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 }
-          opts.on("--strict", "Exit 1 if any plugin failed to load (CI gate)") { options[:strict] = true }
-          opts.on("--capabilities", "Emit the per-plugin extension-protocol catalogue (ADR-37)") do
-            options[:capabilities] = true
-          end
-        end.parse!(@argv)
-        validate!(options)
+        option_parser(options).parse!(@argv)
         options
       end
 
-      def validate!(options)
-        return if %w[text json].include?(options.fetch(:format))
-
-        raise OptionParser::InvalidArgument, "unsupported format: #{options.fetch(:format)}"
-      end
-
       # Runs the plugin loader against the project configuration and returns a row per declared plugin entry. Each row
       # is a plain Hash with the fields enumerated in the class docstring so the renderer (text + JSON) reads from a
       # single shape.
@@ -204,7 +203,7 @@ module Rigor
           .merge(load_error: nil)
       end
 
-      # ADR-37 narrow extension protocols. Unlike the 10 declarative manifest fields, these are class-level DSLs
+      # ADR-37 narrow extension protocols. Unlike the declarative manifest fields, these are class-level DSLs
       # (`node_rule` / `dynamic_return` / `narrowing_facts`), so they are read off the plugin class rather than the
       # manifest. The gate values — node types, receiver class names, specified method names — are the greppable,
       # enumerable surface the capability catalogue exposes.
@@ -233,6 +232,8 @@ module Rigor
           signature_paths: signature_path_rows(plugin),
           open_receivers: manifest.open_receivers.dup,
           owns_receivers: manifest.owns_receivers.dup,
+          per_invocation_classes: manifest.per_invocation_classes.dup,
+          per_invocation_non_action_macros: manifest.per_invocation_non_action_macros.map(&:to_s),
           produces: manifest.produces.map(&:to_s),
           consumes: manifest.consumes.map { |c| "#{c.plugin_id}/#{c.name}#{'?' if c.optional}" },
           source_rbs_synthesizer: !manifest.source_rbs_synthesizer.nil?
@@ -265,6 +266,8 @@ module Rigor
           signature_paths: [],
           open_receivers: [],
           owns_receivers: [],
+          per_invocation_classes: [],
+          per_invocation_non_action_macros: [],
           produces: [],
           consumes: [],
           block_as_methods: 0,
@@ -345,6 +348,7 @@ module Rigor
             config: {},
             signature_paths: [],
             open_receivers: [], owns_receivers: [], produces: [], consumes: [],
+            per_invocation_classes: [], per_invocation_non_action_macros: [],
             block_as_methods: 0, heredoc_templates: 0, trait_registries: 0,
             type_node_resolvers: 0,
             hkt_registrations: 0, hkt_definitions: 0,

data/lib/rigor/cli/plugins_renderer.rb

@@ -1,11 +1,12 @@
 # frozen_string_literal: true
 
 require "json"
+require_relative "json_document"
 
 module Rigor
   class CLI
     # Renderer for `rigor plugins`. Produces a human-readable text table and a JSON representation from the same row
-    # shape (the Hash documented on {Rigor::CLI::PluginsCommand#loaded_row}).
+    # shape (the Hash {Rigor::CLI::PluginsCommand#build_rows} returns).
     #
     # The two formats carry the same content; JSON is meant for tooling (SKILLs, CI, editor integrations) while text is
     # for interactive inspection. Rows are printed in the order the loader resolved them.
@@ -44,7 +45,7 @@ module Rigor
             "available" => @inflection.fetch(:available)
           }
         end
-        JSON.pretty_generate(payload)
+        JSON.pretty_generate(JsonDocument.stamp(payload, mode: "status"))
       end
 
       # ADR-37 § "Machine-readable capability catalogue" — the focused per-plugin extension-protocol dump. Only loaded
@@ -53,10 +54,13 @@ module Rigor
       # type-specifier methods, and produced / consumed facts.
       def capabilities_json
         JSON.pretty_generate(
-          {
-            "configuration" => @configuration_path,
-            "capabilities" => loaded_rows.map { |row| capabilities_json_for(row) }
-          }
+          JsonDocument.stamp(
+            {
+              "configuration" => @configuration_path,
+              "capabilities" => loaded_rows.map { |row| capabilities_json_for(row) }
+            },
+            mode: "capabilities"
+          )
         )
       end
 
@@ -185,12 +189,26 @@ module Rigor
         lines = []
         lines << "        open_receivers: #{row[:open_receivers].join(', ')}" if row[:open_receivers].any?
         lines << "        owns_receivers: #{row[:owns_receivers].join(', ')}" if row[:owns_receivers].any?
+        lines.concat(per_invocation_lines(row))
         lines << "        produces: #{row[:produces].join(', ')}" if row[:produces].any?
         lines << "        consumes: #{row[:consumes].join(', ')}" if row[:consumes].any?
         lines.concat(narrow_protocol_lines(row))
         lines
       end
 
+      # ADR-125 — the per-invocation classes a plugin vouches for, and the macros whose arguments name a method that is
+      # not one of their actions.
+      def per_invocation_lines(row)
+        lines = []
+        if row[:per_invocation_classes].any?
+          lines << "        per_invocation_classes: #{row[:per_invocation_classes].join(', ')}"
+        end
+        if row[:per_invocation_non_action_macros].any?
+          lines << "        per_invocation_non_action_macros: #{row[:per_invocation_non_action_macros].join(', ')}"
+        end
+        lines
+      end
+
       # ADR-37 narrow extension protocols (node_rule / dynamic_return / narrowing_facts). Surfaced in the full report
       # alongside the declarative surfaces; `--capabilities` is the focused view.
       def narrow_protocol_lines(row)
@@ -249,8 +267,6 @@ module Rigor
           "signature_paths" => row[:signature_paths].map do |sp|
             { "path" => sp[:path], "exists" => sp[:exists], "rbs_files" => sp[:rbs_files] }
           end,
-          "open_receivers" => row[:open_receivers],
-          "owns_receivers" => row[:owns_receivers],
           "produces" => row[:produces],
           "consumes" => row[:consumes],
           "block_as_methods" => row[:block_as_methods],
@@ -265,6 +281,16 @@ module Rigor
           "dynamic_return_receivers" => row[:dynamic_return_receivers],
           "narrowing_facts_methods" => row[:narrowing_facts_methods],
           "load_error" => row[:load_error]
+        }.merge(receiver_json(row))
+      end
+
+      # ADR-125 — the per-invocation keys are additive; an empty array when the plugin declares none.
+      def receiver_json(row)
+        {
+          "open_receivers" => row[:open_receivers],
+          "owns_receivers" => row[:owns_receivers],
+          "per_invocation_classes" => row[:per_invocation_classes],
+          "per_invocation_non_action_macros" => row[:per_invocation_non_action_macros]
         }
       end
 

data/lib/rigor/cli/protection_fork_scan.rb

@@ -31,8 +31,8 @@ module Rigor
       # @return one entry per path.
       def run(paths:, scanner:, environment:, configuration:, workers:)
         # Force the full RBS load on the parent so children copy-on-write inherit a warm environment rather
-        # than each rebuilding it after the fork (mirrors the check fork pool's parent-side prewarm). A
-        # no-op on the sequential path but cheap.
+        # than each rebuilding it after the fork (mirrors the check fork pool's parent-side prewarm).
+        # Skipped when the run is sequential.
         environment.rbs_loader&.prewarm if Inference::ForkMap.parallel?([workers, paths.size].min)
 
         payloads = Inference::ForkMap.call(items: paths, workers: workers) do |slice|

data/lib/rigor/cli/protection_renderer.rb

@@ -3,6 +3,7 @@
 require "json"
 
 require_relative "../inference/dynamic_origin"
+require_relative "json_document"
 
 module Rigor
   class CLI
@@ -32,7 +33,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, mode: "protection")))
       end
 
       def render_text(report)

data/lib/rigor/cli/show_bleedingedge_command.rb

@@ -6,6 +6,8 @@ require "optionparser"
 require_relative "../bleeding_edge"
 require_relative "../configuration"
 require_relative "command"
+require_relative "options"
+require_relative "json_document"
 
 module Rigor
   class CLI
@@ -34,19 +36,23 @@ module Rigor
         0
       end
 
-      private
-
-      def parse_options
-        options = { format: "text", 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("--config=PATH", "Path to a .rigor.yml (default: auto-discovery).") do |path|
-            options[:config] = path
+            options[:config] = Options.config_path(path)
           end
-        end.parse!(@argv)
+        end
+      end
+
+      private
+
+      def parse_options
+        options = { format: "text", config: nil }
+        option_parser(options).parse!(@argv)
         options
       end
 
@@ -59,13 +65,14 @@ module Rigor
 
       def render_json(configuration)
         selector = configuration.bleeding_edge
-        @out.puts(JSON.pretty_generate(
-                    "overlay" => BleedingEdge.features.map(&:to_h),
-                    "selector" => configuration.to_h.fetch("bleeding_edge"),
-                    "active" => BleedingEdge.active_features(selector).map(&:id),
-                    "unknown_selected" => BleedingEdge.unknown_selected_ids(selector),
-                    "graduated" => BleedingEdge::GRADUATED
-                  ))
+        payload = {
+          "overlay" => BleedingEdge.features.map(&:to_h),
+          "selector" => configuration.to_h.fetch("bleeding_edge"),
+          "active" => BleedingEdge.active_features(selector).map(&:id),
+          "unknown_selected" => BleedingEdge.unknown_selected_ids(selector),
+          "graduated" => BleedingEdge::GRADUATED
+        }
+        @out.puts(JSON.pretty_generate(JsonDocument.stamp(payload)))
       end
 
       def render_text(configuration)