rigortype 0.4.5 → 0.4.7

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,18 +15,12 @@ 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
         return CLI::EXIT_USAGE if options.nil?
 
         config = options.fetch(:config)
-        if config && !File.file?(config)
-          usage_error("no configuration file at #{config}")
-          return CLI::EXIT_USAGE
-        end
-
         configuration = Configuration.load(config)
         config_path = options.fetch(:config) || Configuration.discover
         # The working directory: Rigor auto-detects sig/ and the lockfiles there (lens.md § Serialization).
@@ -40,22 +34,32 @@ 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
       rescue OptionParser::ParseError => e
         usage_error(e.message)
+      rescue Rigor::ConfigurationError => e
+        # The shared --config check (CLI::Options.config_path). Mapped here the way Rigor::CLI#run maps it, so a
+        # direct LensCommand run exits with the usage code too.
+        @err.puts("rigor: #{e.message}")
+        nil
       end
 
       def usage_error(message)

data/lib/rigor/cli/lsp_command.rb

@@ -4,6 +4,7 @@ require_relative "command"
 require_relative "options"
 require_relative "../runtime/jit"
 
+require "json"
 require "optionparser"
 
 module Rigor
@@ -15,6 +16,179 @@ module Rigor
     class LspCommand < Command
       USAGE = "Usage: rigor lsp [options]"
 
+      # Records each JSON-RPC message one per line, prefixed with the direction (`<-` read from the client, `->`
+      # written to it) and a timestamp. Only the message framing is logged; the server's own debug output joins the
+      # same file through `$stderr` (see {#with_debug_output}).
+      #
+      # It never raises into the protocol path. A message the JSON encoder rejects (raw invalid UTF-8 in a string) is
+      # logged as a scrubbed rendering, so its line is still written. Any IO failure disables the log for the rest of
+      # the session: records are dropped, and debug output falls back to `fallback` (the real stderr). Nothing is
+      # `warn`ed into the failing log.
+      class WireLog
+        def initialize(io, fallback)
+          @io = io
+          @fallback = fallback
+          @broken = false
+        end
+
+        def record(direction, message)
+          deliver("#{stamp} #{direction} #{render(message)}\n")
+          nil
+        end
+
+        # Debug output written to `$stderr` while the session runs (`Kernel#warn` calls `write`). The parts are joined
+        # as binary, so an odd encoding in one part cannot raise here.
+        def write(*parts)
+          text = parts.map { |part| part.to_s.b }.join
+          @fallback.write(text) unless deliver(text)
+          text.bytesize
+        end
+
+        def print(*parts)
+          write(*parts)
+          nil
+        end
+
+        def puts(*args)
+          lines = if args.empty?
+                    ["\n"]
+                  else
+                    args.flatten.map { |arg| arg.to_s.end_with?("\n") ? arg.to_s : "#{arg}\n" }
+                  end
+          write(*lines)
+          nil
+        end
+
+        def printf(format_string, *)
+          write(format(format_string, *))
+          nil
+        end
+
+        def putc(char)
+          write(char.is_a?(Integer) ? char.chr : char.to_s[0])
+          char
+        end
+
+        def syswrite(text)
+          write(text)
+        end
+
+        def <<(part)
+          write(part)
+          self
+        end
+
+        def flush
+          self
+        end
+
+        # The exception that escaped the server loop, with its backtrace, so a crash is in the log, not only on stderr.
+        def crash(error)
+          lines = ["#{stamp} ! #{error.class}: #{error.message}\n"]
+          lines.concat((error.backtrace || []).map { |frame| "    #{frame}\n" })
+          text = lines.join
+          @fallback.write(text) unless deliver(text)
+          nil
+        end
+
+        def close
+          @io.close unless @io.closed?
+        end
+
+        # Every other IO method (`tty?`, `closed?`, `fileno`, `sync=`, `to_io` for `system(err: $stderr)`, ...) goes to
+        # the current sink: the file while the log works, the real stderr once it has failed.
+        def method_missing(name, ...)
+          return super unless sink.respond_to?(name)
+
+          sink.public_send(name, ...)
+        end
+
+        def respond_to_missing?(name, include_private = false)
+          sink.respond_to?(name) || super
+        end
+
+        private
+
+        def sink
+          @broken ? @fallback : @io
+        end
+
+        # Writes `text` to the file. Returns false when the log is (or just became) unusable. Only a failure of the
+        # write itself disables the log.
+        def deliver(text)
+          return false if @broken
+
+          @io.write(text)
+          true
+        rescue StandardError
+          @broken = true
+          false
+        end
+
+        def stamp
+          Time.now.strftime("%FT%T.%6N%:z")
+        end
+
+        # The JSON line for `message`. One the encoder rejects (invalid UTF-8, nesting past its limit, a `to_json` that
+        # raises) is rendered from its scrubbed copy, or from its `inspect` when even that does not encode.
+        def render(message)
+          JSON.generate(message)
+        rescue StandardError
+          begin
+            JSON.generate(scrub(message))
+          rescue StandardError
+            JSON.generate(message.inspect)
+          end
+        end
+
+        def scrub(value)
+          case value
+          when Hash then value.to_h { |key, val| [scrub(key), scrub(val)] }
+          when Array then value.map { |item| scrub(item) }
+          when Symbol then scrub(value.to_s).to_sym
+          when String then value.dup.force_encoding(Encoding::UTF_8).scrub
+          else value
+          end
+        end
+      end
+
+      # Wraps the framed reader so every request or notification it yields is logged before the Loop dispatches it.
+      class WireLogReader
+        def initialize(inner, log)
+          @inner = inner
+          @log = log
+        end
+
+        def read(&block)
+          @inner.read do |message|
+            @log.record("<-", message)
+            block.call(message)
+          end
+        end
+
+        def close
+          @inner.close
+        end
+      end
+
+      # Wraps the framed writer so every outgoing message is logged as it goes on the wire. It sits inside
+      # `SynchronizedWriter`, so the log line and the frame it describes are written under the same lock.
+      class WireLogWriter
+        def initialize(inner, log)
+          @inner = inner
+          @log = log
+        end
+
+        def write(message)
+          @log.record("->", message.merge(jsonrpc: "2.0"))
+          @inner.write(message)
+        end
+
+        def close
+          @inner.close
+        end
+      end
+
       # @return CLI exit status.
       def run
         options = parse_options
@@ -26,6 +200,9 @@ module Rigor
           return CLI::EXIT_USAGE
         end
 
+        log = open_wire_log(options.fetch(:log))
+        return CLI::EXIT_USAGE if log == :usage_error
+
         # A long-lived server always outlasts the JIT compile cost, so enable
         # YJIT at boot rather than on the analysis deadline (Runtime::Jit).
         Runtime::Jit.enable_now
@@ -34,23 +211,83 @@ module Rigor
         require_relative "../configuration"
         require "language_server-protocol"
 
-        # STDIN is read frame-by-frame via the gem's `Io::Reader`; STDOUT is wrapped in `SynchronizedWriter` so
-        # concurrent writes from the main dispatch thread + the Debouncer's async threads don't interleave frames. The
-        # Loop runs until either STDIN hits EOF or `server.exited?`; the process then exits with the server's recorded
-        # code (0 after a clean shutdown+exit, 1 otherwise).
-        writer = LanguageServer::SynchronizedWriter.new(
-          ::LanguageServer::Protocol::Transport::Io::Writer.new($stdout)
-        )
-        server, loop_runner = build_server(writer: writer, config_path: options.fetch(:config))
-        loop_runner.run
-        server.exit_code || 0
+        begin
+          serve(config_path: options.fetch(:config), log: log)
+        ensure
+          log&.close
+        end
+      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
+          opts.on("--transport=NAME", "Transport (default: stdio; only stdio supported in v1)") do |value|
+            options[:transport] = value
+          end
+          opts.on("--log=PATH",
+                  "Append the LSP wire log and server debug output to PATH " \
+                  "(default: no wire log; debug output goes to stderr)") do |value|
+            options[:log] = value
+          end
+          Options.add_config(opts, options)
+        end
       end
 
       private
 
+      # STDIN is read frame-by-frame via the gem's `Io::Reader`; STDOUT is wrapped in `SynchronizedWriter` so
+      # concurrent writes from the main dispatch thread + the Debouncer's async threads don't interleave frames. The
+      # Loop runs until either STDIN hits EOF or `server.exited?`; the process then exits with the server's recorded
+      # code (0 after a clean shutdown+exit, 1 otherwise). With a wire log, both directions are logged inside the lock.
+      def serve(config_path:, log:)
+        reader = ::LanguageServer::Protocol::Transport::Io::Reader.new($stdin)
+        frame_writer = ::LanguageServer::Protocol::Transport::Io::Writer.new($stdout)
+        if log
+          reader = WireLogReader.new(reader, log)
+          frame_writer = WireLogWriter.new(frame_writer, log)
+        end
+        writer = LanguageServer::SynchronizedWriter.new(frame_writer)
+        server, loop_runner = build_server(writer: writer, reader: reader, config_path: config_path)
+        with_debug_output(log) { loop_runner.run }
+        server.exit_code || 0
+      end
+
+      # Opens PATH for appending with synchronous writes, so a crash loses no logged line. Returns nil without a
+      # PATH, the open file, or `:usage_error` after reporting why it could not be opened.
+      def open_wire_log(path)
+        return nil if path.nil?
+
+        io = File.new(path, "a")
+        io.sync = true
+        WireLog.new(io, $stderr)
+      rescue SystemCallError => e
+        @err.puts("rigor lsp: cannot open --log file #{path.inspect}: #{e.message}")
+        :usage_error
+      end
+
+      # Routes the server's debug output (`warn` and the Ruby runtime's warnings, both written to `$stderr`) into the
+      # wire log for the length of the session. An exception that escapes the loop is written to the log before
+      # `$stderr` is restored and the exception is re-raised. Without a log, `$stderr` is left alone.
+      def with_debug_output(log)
+        return yield if log.nil?
+
+        saved = $stderr
+        begin
+          $stderr = log
+          yield
+        rescue StandardError, ScriptError, SystemStackError => e
+          log.crash(e)
+          raise
+        ensure
+          $stderr = saved
+        end
+      end
+
       # Builds the full collaborator graph from a fresh `Configuration` + `ProjectContext`. Returns `[server, loop]` so
       # the caller drives the loop and reads `server.exit_code` for the process exit status.
-      def build_server(writer:, config_path:) # rubocop:disable Metrics/MethodLength
+      def build_server(writer:, reader:, config_path:) # rubocop:disable Metrics/MethodLength
         configuration = Configuration.load(config_path)
         # ProjectContext caches Environment + Cache::Store across requests so hover / publish hit the warm path.
         # Invalidated by `workspace/didChangeWatchedFiles` and `workspace/didChangeConfiguration`; every save round
@@ -89,7 +326,7 @@ module Rigor
           project_context: project_context
         )
         loop_runner = LanguageServer::Loop.new(
-          reader: ::LanguageServer::Protocol::Transport::Io::Reader.new($stdin),
+          reader: reader,
           writer: writer,
           server: server
         )
@@ -99,17 +336,7 @@ module Rigor
       def parse_options
         options = { transport: "stdio", log: nil, config: nil }
 
-        parser = OptionParser.new do |opts|
-          opts.banner = USAGE
-          opts.on("--transport=NAME", "Transport (default: stdio; only stdio supported in v1)") do |value|
-            options[:transport] = value
-          end
-          opts.on("--log=PATH", "Write LSP wire log + server debug to PATH (default: stderr)") do |value|
-            options[:log] = value
-          end
-          Options.add_config(opts, options)
-        end
-        parser.parse!(@argv)
+        option_parser(options).parse!(@argv)
         options
       rescue OptionParser::ParseError => e
         @err.puts(e.message)

data/lib/rigor/cli/mcp_command.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "command"
+require_relative "options"
 require_relative "../runtime/jit"
 
 require "optionparser"
@@ -41,12 +42,10 @@ module Rigor
         0
       end
 
-      private
-
-      def parse_options
-        options = { transport: "stdio", 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("--transport=NAME",
                   "Transport (default: stdio; only stdio is supported in v1)") do |value|
@@ -54,10 +53,17 @@ module Rigor
           end
           opts.on("--config=PATH",
                   "Session-level default config path (individual tool calls may override)") do |value|
-            options[:config] = value
+            options[:config] = Options.config_path(value)
           end
         end
-        parser.parse!(@argv)
+      end
+
+      private
+
+      def parse_options
+        options = { transport: "stdio", config: nil }
+
+        option_parser(options).parse!(@argv)
         options
       rescue OptionParser::ParseError => e
         @err.puts(e.message)

data/lib/rigor/cli/mutation_fork_scan.rb

@@ -40,7 +40,7 @@ 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. A no-op on the sequential path but cheap.
+        # than each rebuilding it after the fork. 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/mutation_protection_renderer.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "json"
+require_relative "json_document"
 
 module Rigor
   class CLI
@@ -22,7 +23,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)
@@ -46,7 +47,7 @@ module Rigor
       end
 
       # Issue #686 — the count that makes the command exit non-zero, on stdout beside the ratio it qualifies
-      # (the stderr twin in `CoverageMutation#warn_unmeasured_files` carries the explanation).
+      # (the stderr twin in {MeasurementIntegrityWarning} carries the explanation).
       def render_unmeasured_files(report)
         count = report.unmeasured_files
         return if count.zero?