rigortype 0.4.6 → 0.4.7

data/lib/rigor/cli/skill_command.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "optparse"
+
 require_relative "command"
 require_relative "../rooted_glob"
 
@@ -77,6 +79,28 @@ module Rigor
       # up.
       SKILLS_ROOT = File.expand_path("../../../skills", __dir__).freeze
 
+      # The parser of `rigor skill`, built without parsing anything: the catalogue reads its flags from it (ADR-126
+      # WD3). The positional grammar is read by hand in {#run}, so this describes the switches and parses nothing.
+      def option_parser(options = {})
+        OptionParser.new do |opts|
+          opts.banner = USAGE.lines.first.chomp
+          opts.on("--full NAME", "Print the SKILL.md body and its references/ inline") { |v| options[:full] = v }
+          opts.on("--path NAME", "Print the absolute path of the SKILL.md file") { |v| options[:path] = v }
+          opts.on("--list", "List bundled skills (name + absolute path)") { options[:list] = true }
+          opts.on("--describe", "Report project state and recommend the next skill") { options[:describe] = true }
+        end
+      end
+
+      # The parser of `rigor skill describe` and `rigor describe`; `banner` is the usage line of the spelling used.
+      def self.describe_option_parser(banner = "Usage: rigor skill describe [--deep]", options = {})
+        OptionParser.new do |opts|
+          opts.banner = banner
+          opts.on("--deep", "Run `rigor check` first and route the recommendation on its result") do
+            options[:deep] = true
+          end
+        end
+      end
+
       # @return CLI exit status.
       def run
         case @argv.first
@@ -87,7 +111,7 @@ module Rigor
           0
         when "describe", "--describe"
           @argv.shift
-          run_describe
+          run_describe("Usage: rigor skill describe [--deep]")
         when "--list"
           @argv.shift
           run_list
@@ -176,7 +200,12 @@ module Rigor
       # `--deep` is the one opt-in that breaks the "never runs `rigor check`" guarantee — and only for the invocation
       # that asks for it (issue #148 / ADR-73 § "Field-trial follow-ups"). It runs a real check and lets the result
       # pick the headline; the un-flagged command is unchanged, down to loading no analysis code at all.
-      def run_describe
+      def run_describe(usage)
+        if @argv.intersect?(%w[-h --help])
+          @out.puts(usage)
+          return 0
+        end
+
         deep = !@argv.delete("--deep").nil?
         unknown = @argv.first
         return usage_error("unknown option for `describe`: #{unknown}") unless unknown.nil?
@@ -222,7 +251,7 @@ module Rigor
         discover_skills.find { |s| s.fetch(:name) == name }
       end
 
-      # The `references/*.md` files bundled alongside a skill, sorted so the `NN-` prefixes drive read order.
+      # The `references/*.md` files bundled alongside a skill.
       def reference_files(skill)
         dir = File.join(File.dirname(skill.fetch(:path)), "references")
         return [] unless File.directory?(dir)

data/lib/rigor/cli/skill_deep_probe.rb

@@ -96,7 +96,7 @@ module Rigor
         end
       end
 
-      # The `rigor-doctor` signal, read exactly as `rigor doctor` itself reads it: an RBS environment that built to
+      # The `rigor-doctor` signal: an RBS environment that built to
       # zero classes (analysis is hollow, so every other count is meaningless), or a `configuration-error` the run
       # already emitted. Checked first — with a broken setup the remaining diagnostics are not evidence of anything.
       def broken_environment?(result)

data/lib/rigor/cli/skill_describe.rb

@@ -361,7 +361,7 @@ module Rigor
       end
 
       # The one-line essence of a skill's frontmatter `description`, read live from the SKILL.md so the catalogue can
-      # never go stale relative to the shipped skill. Drops the `Triggers:` / `NOT for` tail and caps the length.
+      # never go stale relative to the shipped skill. Drops the `Triggers:` tail and caps the length.
       def catalog_blurb(path)
         text = frontmatter(path).fetch("description", "").to_s.strip.tr("\n", " ").squeeze(" ")
         head = text.split(/\s*Triggers?:/, 2).first.to_s.strip

data/lib/rigor/cli/trace_command.rb

@@ -12,6 +12,7 @@ require_relative "../inference/flow_tracer"
 require_relative "../inference/scope_indexer"
 require_relative "command"
 require_relative "trace_renderer"
+require_relative "json_document"
 require_relative "../project_environment"
 
 module Rigor
@@ -43,15 +44,12 @@ module Rigor
         execute(file: file, options: options)
       end
 
-      private
-
-      def parse_options
-        options = { format: "text", delay: nil, verbose: false, line: nil, config: nil }
-        parser = OptionParser.new do |opts|
+      # 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 (animation) or json (raw event stream)") do |value|
-            options[:format] = value
-          end
+          Options.add_format(opts, options, "Output format: text (animation) or json (raw event stream)")
           opts.on("--delay=SECONDS", Float,
                   "Autoplay with SECONDS between frames (default: step on key press)") do |value|
             options[:delay] = value
@@ -62,7 +60,13 @@ module Rigor
           opts.on("--verbose", "Include every expression enter/result frame") { options[:verbose] = true }
           Options.add_config(opts, options)
         end
-        parser.parse!(@argv)
+      end
+
+      private
+
+      def parse_options
+        options = { format: "text", delay: nil, verbose: false, line: nil, config: nil }
+        option_parser(options).parse!(@argv)
         options
       end
 
@@ -82,6 +86,7 @@ module Rigor
 
         if options.fetch(:format) == "json"
           @out.puts(JSON.pretty_generate(frames.map { |event| event_to_h(event) }))
+          @err.puts(JsonDocument::SHAPE_NOTICES.fetch(:trace))
           return 0
         end
 

data/lib/rigor/cli/triage_command.rb

@@ -36,14 +36,13 @@ module Rigor
         0
       end
 
-      private
-
-      def parse_options
-        options = { config: nil, format: "text", top: 10, sections: DEFAULT_SECTIONS, include_info: false }
+      # 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 }
+          Options.add_format(opts, options, "Output format: text (default) or json")
           opts.on("--top=N", Integer, "Hotspot-file count (default 10)") { |v| options[:top] = v }
           opts.on("--include-info",
                   "Route info diagnostics into distribution / selectors / hotspots " \
@@ -57,15 +56,15 @@ module Rigor
           opts.on("--selectors-only", "Print only the class/method selectors section") do
             options[:sections] = %i[selectors]
           end
-        end.parse!(@argv)
-        validate!(options)
-        options
+        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", top: 10, sections: DEFAULT_SECTIONS, include_info: false }
+        option_parser(options).parse!(@argv)
+        options
       end
 
       # Sequential, cache-backed, no run-stats: triage only needs the diagnostic stream, and sequential keeps the rule

data/lib/rigor/cli/triage_renderer.rb

@@ -3,6 +3,7 @@
 require "json"
 
 require_relative "../triage"
+require_relative "json_document"
 
 module Rigor
   class CLI
@@ -17,7 +18,7 @@ module Rigor
       end
 
       def json
-        JSON.pretty_generate(Triage.report_to_h(@report))
+        JSON.pretty_generate(JsonDocument.stamp(Triage.report_to_h(@report)))
       end
 
       def text

data/lib/rigor/cli/type_of_command.rb

@@ -13,6 +13,7 @@ require_relative "../inference/scope_indexer"
 require_relative "../inference/precision_scanner"
 require_relative "../source/node_children"
 require_relative "type_of_renderer"
+require_relative "json_document"
 require_relative "type_of_template_probe"
 require_relative "command"
 require_relative "options"
@@ -29,7 +30,7 @@ module Rigor
     # Encapsulating the command in its own class keeps `Rigor::CLI` focused on dispatching and lets us evolve the
     # type-of UX (extra flags, watch mode, streaming output) without bloating the CLI shell. Output formatting is
     # delegated to {TypeOfRenderer}.
-    class TypeOfCommand < Command
+    class TypeOfCommand < Command # rubocop:disable Metrics/ClassLength
       include TypeOfTemplateProbe
 
       USAGE = "Usage: rigor type-of [options] FILE:LINE[:COL] [FILE:LINE[:COL] ...]"
@@ -65,19 +66,24 @@ module Rigor
         execute(targets: targets, options: options, buffer: buffer)
       end
 
-      private
-
-      def parse_options
-        options = { format: "text", trace: false, config: nil, tmp_file: nil, instead_of: nil }
-
-        parser = OptionParser.new do |opts|
+      # 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 or json") { |value| options[:format] = value }
+          Options.add_format(opts, options, "Output format: text or json")
           opts.on("--trace", "Record fail-soft fallbacks via FallbackTracer") { options[:trace] = true }
           Options.add_config(opts, options)
           Options.add_editor_mode(opts, options)
         end
-        parser.parse!(@argv)
+      end
+
+      private
+
+      def parse_options
+        options = { format: "text", trace: false, config: nil, tmp_file: nil, instead_of: nil }
+
+        option_parser(options).parse!(@argv)
 
         options
       end
@@ -101,7 +107,7 @@ module Rigor
         results = results_by_target.compact.flatten(1)
         return 1 if results.empty?
 
-        TypeOfRenderer.new(out: @out).render(results, format: options.fetch(:format))
+        TypeOfRenderer.new(out: @out, err: @err).render(results, format: options.fetch(:format))
         0
       end
 
@@ -206,7 +212,6 @@ module Rigor
         end
       end
 
-      # `presentation` is the Result's optional `enumeration:` / `location_mapper:`.
       def type_result(file, line, column, node, scope_index, options, **presentation)
         tracer = options[:trace] ? Inference::FallbackTracer.new : nil
         type = scope_index[node].type_of(node, tracer: tracer)

data/lib/rigor/cli/type_of_project_scope.rb

@@ -16,11 +16,8 @@ module Rigor
       module_function
 
       def build(environment:, configuration:, buffer: nil)
-        base = Scope.empty(environment: environment)
         seed = Protection::DiscoverySeed.from_snapshot(configuration: configuration, buffer: buffer)
-        return base if seed.nil? || seed.empty?
-
-        base.with_discovery(base.discovery.with(**seed))
+        Protection::DiscoverySeed.seeded_scope(environment: environment, seed: seed)
       end
     end
   end

data/lib/rigor/cli/type_of_renderer.rb

@@ -4,6 +4,7 @@ require "json"
 require "optionparser"
 
 require_relative "renderable"
+require_relative "json_document"
 
 module Rigor
   class CLI
@@ -14,8 +15,9 @@ module Rigor
     class TypeOfRenderer
       include Renderable
 
-      def initialize(out:)
+      def initialize(out:, err: nil)
         @out = out
+        @err = err
       end
 
       private
@@ -96,6 +98,7 @@ module Rigor
         enumerations = line_enumerations(list)
         payload[:line_enumerations] = enumerations unless enumerations.empty?
         @out.puts(JSON.pretty_generate(payload))
+        @err&.puts(JsonDocument::SHAPE_NOTICES.fetch(:type_of))
       end
 
       def line_enumerations(results)

data/lib/rigor/cli/type_scan_command.rb

@@ -38,15 +38,12 @@ module Rigor
         determine_exit(report, options)
       end
 
-      private
-
-      def parse_options
-        options = { format: "text", limit: 10, show_recognized: false, threshold: nil,
-                    config: nil }
-
-        parser = OptionParser.new do |opts|
+      # 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 or json") { |value| options[:format] = value }
+          Options.add_format(opts, options, "Output format: text or json")
           Options.add_config(opts, options)
           opts.on("--limit=N", Integer, "Max example events to print (text only)") do |value|
             options[:limit] = value
@@ -58,7 +55,15 @@ module Rigor
             options[:threshold] = value
           end
         end
-        parser.parse!(@argv)
+      end
+
+      private
+
+      def parse_options
+        options = { format: "text", limit: 10, show_recognized: false, threshold: nil,
+                    config: nil }
+
+        option_parser(options).parse!(@argv)
 
         options
       end

data/lib/rigor/cli/type_scan_renderer.rb

@@ -4,6 +4,7 @@ require "json"
 require "optionparser"
 
 require_relative "renderable"
+require_relative "json_document"
 
 module Rigor
   class CLI
@@ -100,7 +101,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))))
       end
 
       def json_payload(report)

data/lib/rigor/cli/unused_command.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "optionparser"
+require_relative "json_document"
 require "json"
 
 require_relative "../configuration"
@@ -67,6 +68,23 @@ 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("--entry-point=GLOB", "Treat declarations in files matching GLOB as roots (repeatable)") do |v|
+            options[:entry_points] << v
+          end
+          opts.on("--limit=N", Integer, "Print at most N candidates (default: all)") { |v| options[:limit] = v }
+          # WD5 — refuse rather than silently absorb. A reachability answer is sound only over a full run, and a
+          # user who asked for the fast path must not silently get the slow one.
+          opts.on("--incremental", "(unsupported)") { options[:incremental] = true }
+        end
+      end
+
       private
 
       # A scan's role and the spelling it records depend on the root and the working directory (#1760): a role
@@ -120,20 +138,8 @@ module Rigor
 
       def parse_options
         options = { config: nil, format: "text", entry_points: [], limit: nil }
-        parser = 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("--entry-point=GLOB", "Treat declarations in files matching GLOB as roots (repeatable)") do |v|
-            options[:entry_points] << v
-          end
-          opts.on("--limit=N", Integer, "Print at most N candidates (default: all)") { |v| options[:limit] = v }
-          # WD5 — refuse rather than silently absorb. A reachability answer is sound only over a full run, and a
-          # user who asked for the fast path must not silently get the slow one.
-          opts.on("--incremental", "(unsupported)") { options[:incremental] = true }
-        end
-        parser.parse!(@argv)
-        return usage_error(parser) if options[:incremental]
+        option_parser(options).parse!(@argv)
+        return usage_error if options[:incremental]
 
         options
       rescue OptionParser::ParseError => e
@@ -141,7 +147,7 @@ module Rigor
         :usage_error
       end
 
-      def usage_error(_parser)
+      def usage_error
         @err.puts("rigor unused does not support --incremental: reachability is only sound over a whole-project " \
                   "run, so an incremental pass would report constants as unused merely because the files that " \
                   "reference them were served from cache. Re-run without --incremental.")
@@ -379,6 +385,9 @@ module Rigor
                                       required_features: ProjectEnvironment.required_features(configuration),
                                       **ProjectEnvironment.dependency_discovery_options(configuration))
         ->(fqn) { !env.singleton_for_name(fqn).nil? }
+      rescue Environment::CoreRootError
+        # Issue #2517 — answering "unknown" for every name would report against no core at all.
+        raise
       rescue StandardError
         ->(_fqn) { false }
       end
@@ -413,7 +422,7 @@ module Rigor
       end
 
       def json(report, options, supply)
-        JSON.pretty_generate(
+        payload = {
           declared: report.declared, reachable: report.reachable, roots: report.roots, edges: report.edges,
           namespaces: report.namespaces,
           plugin_roots: supply.supplied, plugin_roots_unmatched: supply.unmatched,
@@ -421,7 +430,8 @@ module Rigor
           undecidable: limited(report.undecidable, options).map do |u|
             { name: u.fqn, path: u.path, line: u.line, reason: u.reason }
           end
-        )
+        }
+        JSON.pretty_generate(JsonDocument.stamp(payload))
       end
 
       def rows_json(rows, options)

data/lib/rigor/cli/upgrade_command.rb

@@ -15,6 +15,11 @@ module Rigor
 
       # @return CLI exit status.
       def run
+        if @argv.intersect?(%w[-h --help])
+          @out.puts(USAGE)
+          return 0
+        end
+
         @out.puts("rigor upgrade: No migration target available yet (ADR-50 WD7, queued).")
         @out.puts("Current version: #{Rigor::VERSION}")
         0