rigortype 0.1.16 → 0.1.17

data/lib/rigor/cache/rbs_known_class_names.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "rbs_descriptor"
+require_relative "rbs_cache_producer"
 
 module Rigor
   module Cache
@@ -18,19 +19,12 @@ module Rigor
     # Cache descriptor shape is shared with {RbsConstantTable} via
     # {RbsDescriptor.build}; a single signature change or rbs gem
     # bump invalidates both producers in lockstep.
-    class RbsKnownClassNames
+    class RbsKnownClassNames < RbsCacheProducer
       PRODUCER_ID = "rbs.known_class_names"
 
       # @param loader [Rigor::Environment::RbsLoader]
       # @param store [Rigor::Cache::Store]
       # @return [Set<String>]
-      def self.fetch(loader:, store:)
-        descriptor = RbsDescriptor.build(loader)
-        store.fetch_or_compute(producer_id: PRODUCER_ID, params: {}, descriptor: descriptor) do
-          compute(loader)
-        end
-      end
-
       def self.compute(loader)
         names = Set.new
         loader.each_known_class_name { |name| names << name }

data/lib/rigor/cache/store.rb

@@ -44,9 +44,10 @@ module Rigor
       #   invocations can read from the same cache concurrently
       #   without churning it. See
       #   `docs/design/20260516-editor-mode.md` § "Cache behaviour".
-      def initialize(root:, read_only: false)
+      def initialize(root:, read_only: false, max_bytes: nil)
         @root = root.to_s.dup.freeze
         @read_only = read_only
+        @max_bytes = max_bytes&.then { |n| Integer(n) }
         @hits = 0
         @misses = 0
         @writes = 0
@@ -197,6 +198,81 @@ module Rigor
         value
       end
 
+      # ADR-45 — record-and-validate variant. Unlike {fetch_or_compute},
+      # which keys the entry on its descriptor (so the inputs MUST be
+      # known before running), this keys on `key_descriptor` (the stable
+      # inputs known up front) and stores, alongside the value, a
+      # `dependency_descriptor` of the files the value actually read —
+      # including inputs discovered DURING the computation (e.g. a plugin
+      # reading a file mid-analysis). On the next run the stored
+      # dependencies are re-validated against the filesystem
+      # ({Descriptor#fresh?}); a stale dependency forces a recompute.
+      #
+      # The block MUST return `[value, dependency_descriptor]`. Disk reads
+      # are not in-process-memoised — validation always re-checks the
+      # filesystem — but a single run only looks up once.
+      def fetch_or_validate(producer_id:, key_descriptor:, params: {}, serialize: nil, deserialize: nil)
+        validate_producer_id!(producer_id)
+        ensure_schema_version!
+
+        key = key_descriptor.cache_key_for(producer_id: producer_id, params: params)
+        path = entry_path(producer_id, key)
+        cached = read_entry(path, deserialize: deserialize)
+        if cached && (pair = cached.value).is_a?(Array) && pair.size == 2 &&
+           pair[1].is_a?(Descriptor) && pair[1].fresh?
+          @monitor.synchronize { record(:hits, producer_id) }
+          return pair[0]
+        end
+
+        value, dependency_descriptor = block_given? ? yield : [nil, Descriptor.new]
+        wrote = false
+        unless @read_only
+          # A cache write must never break the run. If the value is not
+          # Marshal-clean (or any disk error occurs) skip caching and
+          # return the freshly-computed value — the next run recomputes.
+          begin
+            write_entry(path, key_descriptor, [value, dependency_descriptor], serialize: serialize)
+            wrote = true
+          rescue StandardError
+            wrote = false
+          end
+        end
+        @monitor.synchronize do
+          record(:misses, producer_id)
+          record(:writes, producer_id) if wrote
+        end
+        value
+      end
+
+      # ADR-6 § "Eviction" — LRU pass over the on-disk cache. No-op when
+      # `max_bytes:` was not configured or the store is read-only.
+      # Walks all `.entry` files, sorts by mtime ascending (oldest = least
+      # recently used), and unlinks from the oldest until the total is at
+      # or below the cap. Touch-on-disk-read ({read_entry}) is the
+      # cross-process LRU signal: every disk hit (not in-process-memo hit)
+      # updates the mtime so recently-read entries survive the eviction pass.
+      # Any FS error is swallowed — eviction must never break a run.
+      def evict!
+        return if @max_bytes.nil? || @read_only
+
+        entries = collect_entry_stats
+        total   = entries.sum { |e| e[:bytes] }
+        return if total <= @max_bytes
+
+        entries.sort_by! { |e| e[:mtime] }
+        entries.each do |entry|
+          break if total <= @max_bytes
+
+          File.unlink(entry[:path])
+          total -= entry[:bytes]
+        rescue StandardError
+          next
+        end
+        nil
+      rescue StandardError
+        nil
+      end
+
       private
 
       Entry = Data.define(:descriptor_bytes, :value)
@@ -238,6 +314,7 @@ module Rigor
         value = safe_load(value_bytes, deserialize)
         return nil if value.equal?(LOAD_FAILED)
 
+        touch_for_lru(path) if @max_bytes
         Entry.new(descriptor_bytes, value)
       end
 
@@ -370,6 +447,27 @@ module Rigor
         end
       end
 
+      # Updates both atime and mtime of `path` to the current time — the
+      # cross-process LRU signal used by {evict!}. Best-effort: any FS
+      # error (read-only mount, deleted file) is silently ignored.
+      def touch_for_lru(path)
+        now = Time.now
+        File.utime(now, now, path)
+      rescue StandardError
+        nil
+      end
+
+      # Returns an array of `{ path:, mtime:, bytes: }` hashes for every
+      # `.entry` file under the cache root, skipping unreadable entries.
+      def collect_entry_stats
+        Dir.glob(File.join(@root, "**", "*.entry")).filter_map do |path|
+          stat = File.stat(path)
+          { path: path, mtime: stat.mtime, bytes: stat.size }
+        rescue StandardError
+          nil
+        end
+      end
+
       def read_varint(bytes, offset)
         result = 0
         shift = 0

data/lib/rigor/cli/annotate_command.rb

@@ -9,6 +9,7 @@ require_relative "../scope"
 require_relative "../inference/def_return_typer"
 require_relative "../inference/scope_indexer"
 require_relative "prism_colorizer"
+require_relative "command"
 
 module Rigor
   class CLI
@@ -25,19 +26,13 @@ module Rigor
     # since the appended text is always a comment — and printed to
     # stdout with IRB-style syntax highlighting via
     # {PrismColorizer}.
-    class AnnotateCommand
+    class AnnotateCommand < Command
       USAGE = "Usage: rigor annotate [options] FILE"
 
       # Appended ` #=> dump_type: <type>` suffix. Matched and
       # stripped before re-annotating so re-running is idempotent.
       ANNOTATION_PATTERN = /\s*#=>\s*dump_type:.*\z/
 
-      def initialize(argv:, out:, err:)
-        @argv = argv
-        @out = out
-        @err = err
-      end
-
       # @return [Integer] CLI exit status.
       def run
         options = parse_options

data/lib/rigor/cli/baseline_command.rb

@@ -6,6 +6,7 @@ require_relative "../analysis/baseline"
 require_relative "../analysis/runner"
 require_relative "../cache/store"
 require_relative "../configuration"
+require_relative "command"
 
 module Rigor
   class CLI
@@ -20,18 +21,12 @@ module Rigor
     #   rigor baseline dump
     #   rigor baseline drift
     #   rigor baseline prune
-    class BaselineCommand # rubocop:disable Metrics/ClassLength
+    class BaselineCommand < Command # rubocop:disable Metrics/ClassLength
       EXIT_USAGE = 64
       DEFAULT_BASELINE_PATH = ".rigor-baseline.yml"
 
       SUBCOMMANDS = %w[generate regenerate dump drift prune].freeze
 
-      def initialize(argv:, out: $stdout, err: $stderr)
-        @argv = argv
-        @out = out
-        @err = err
-      end
-
       def run
         subcommand = @argv.shift
         case subcommand

data/lib/rigor/cli/command.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Rigor
+  class CLI
+    # Base class for the `rigor <subcommand>` command objects.
+    #
+    # Every subcommand captured the same invariant wiring — the argument
+    # vector plus the output and error streams — in an identical
+    # `initialize(argv:, out:, err:)`, and defaulted the streams
+    # inconsistently (some to `$stdout` / `$stderr`, most not at all).
+    # Centralising it here gives one consistent shape and lets a test
+    # instantiate a command with just `argv:` (the streams default so a
+    # spec can pass a `StringIO` for one and ignore the other).
+    #
+    # Subclasses read the `@argv` / `@out` / `@err` ivars directly, as
+    # they did before.
+    class Command
+      def initialize(argv:, out: $stdout, err: $stderr)
+        @argv = argv
+        @out = out
+        @err = err
+      end
+
+      private
+
+      # Expands `args` (a mix of files and directories) into a unique
+      # list of `.rb` paths, recursing into directories. Returns nil —
+      # after writing `<command_name>: not a file or directory: <arg>` to
+      # `@err` — on the first arg that is neither. Shared by the
+      # path-walking commands (`type-scan`, `coverage`).
+      def collect_paths(args, command_name:)
+        paths = []
+        args.each do |arg|
+          if File.directory?(arg)
+            paths.concat(Dir.glob(File.join(arg, "**/*.rb")))
+          elsif File.file?(arg)
+            paths << arg
+          else
+            @err.puts("#{command_name}: not a file or directory: #{arg}")
+            return nil
+          end
+        end
+        paths.uniq
+      end
+    end
+  end
+end

data/lib/rigor/cli/coverage_command.rb

@@ -9,6 +9,7 @@ require_relative "../inference/precision_scanner"
 require_relative "../scope"
 require_relative "coverage_report"
 require_relative "coverage_renderer"
+require_relative "command"
 
 module Rigor
   class CLI
@@ -25,19 +26,13 @@ module Rigor
     #   0  — scan complete, precision ratio ≥ threshold (or no threshold given)
     #   1  — precision ratio < threshold, or parse errors encountered
     #   64 — usage error
-    class CoverageCommand
+    class CoverageCommand < Command
       USAGE = "Usage: rigor coverage [options] PATH..."
 
-      def initialize(argv:, out:, err:)
-        @argv = argv
-        @out = out
-        @err = err
-      end
-
       # @return [Integer] CLI exit status.
       def run
         options = parse_options
-        paths = collect_paths(@argv)
+        paths = collect_paths(@argv, command_name: "coverage")
         return CLI::EXIT_USAGE if paths.nil?
         return usage_error if paths.empty?
 
@@ -64,21 +59,6 @@ module Rigor
         options
       end
 
-      def collect_paths(args)
-        paths = []
-        args.each do |arg|
-          if File.directory?(arg)
-            paths.concat(Dir.glob(File.join(arg, "**/*.rb")))
-          elsif File.file?(arg)
-            paths << arg
-          else
-            @err.puts("coverage: not a file or directory: #{arg}")
-            return nil
-          end
-        end
-        paths.uniq
-      end
-
       def usage_error
         @err.puts("coverage: at least one path is required")
         @err.puts(USAGE)

data/lib/rigor/cli/coverage_renderer.rb

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
 
 require "json"
+require_relative "renderable"
 
 module Rigor
   class CLI
     # Renders a `CoverageReport` as terminal-friendly text or JSON.
     class CoverageRenderer
+      include Renderable
+
       TIER_LABELS = {
         constant: "constant",
         nominal: "nominal",
@@ -21,14 +24,6 @@ module Rigor
         @out = out
       end
 
-      def render(report, format:)
-        case format
-        when "text" then render_text(report)
-        when "json" then render_json(report)
-        else raise OptionParser::InvalidArgument, "unsupported format: #{format}"
-        end
-      end
-
       private
 
       def render_text(report)

data/lib/rigor/cli/diff_command.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "command"
+
 require "json"
 require "optionparser"
 
@@ -29,15 +31,9 @@ module Rigor
     # is `1` when any new diagnostic appears, `0` otherwise —
     # so adding new errors fails CI but legacy errors recorded
     # in the baseline don't.
-    class DiffCommand
+    class DiffCommand < Command
       USAGE = "Usage: rigor diff [options] <baseline.json> [paths...]"
 
-      def initialize(argv:, out:, err:)
-        @argv = argv
-        @out = out
-        @err = err
-      end
-
       # @return [Integer] CLI exit status.
       def run
         options = parse_options

data/lib/rigor/cli/explain_command.rb

@@ -4,6 +4,7 @@ require "json"
 require "optionparser"
 
 require_relative "../analysis/rule_catalog"
+require_relative "command"
 
 module Rigor
   class CLI
@@ -17,15 +18,9 @@ module Rigor
     # beyond the rendered catalog. Useful when a user sees a
     # diagnostic in the editor and wants to know what the rule
     # means without leaving the terminal.
-    class ExplainCommand
+    class ExplainCommand < Command
       USAGE = "Usage: rigor explain [options] [<rule>]"
 
-      def initialize(argv:, out:, err:)
-        @argv = argv
-        @out = out
-        @err = err
-      end
-
       # @return [Integer] CLI exit status.
       def run
         options = parse_options

data/lib/rigor/cli/lsp_command.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "command"
+
 require "optionparser"
 
 module Rigor
@@ -11,15 +13,9 @@ module Rigor
     # The actual stdio JSON-RPC reader / writer is queued for slice 2;
     # invoking `rigor lsp` at slice 1 returns immediately after
     # validating the transport flag.
-    class LspCommand
+    class LspCommand < Command
       USAGE = "Usage: rigor lsp [options]"
 
-      def initialize(argv:, out:, err:)
-        @argv = argv
-        @out = out
-        @err = err
-      end
-
       # @return [Integer] CLI exit status.
       def run
         options = parse_options

data/lib/rigor/cli/mcp_command.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "command"
+
 require "optionparser"
 
 module Rigor
@@ -13,15 +15,9 @@ module Rigor
     # Slice 1 ships the stdio transport with seven read-only tools:
     # rigor_check, rigor_type_of, rigor_triage, rigor_annotate,
     # rigor_sig_gen, rigor_explain, rigor_coverage.
-    class McpCommand
+    class McpCommand < Command
       USAGE = "Usage: rigor mcp [options]"
 
-      def initialize(argv:, out:, err:)
-        @argv = argv
-        @out = out
-        @err = err
-      end
-
       # @return [Integer] CLI exit status.
       def run
         options = parse_options

data/lib/rigor/cli/options.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative "../analysis/buffer_binding"
+
+module Rigor
+  class CLI
+    # Shared option plumbing for the subcommands.
+    #
+    # Today it owns the editor-mode surface that `rigor check` and
+    # `rigor type-of` both expose: the `--tmp-file` / `--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.
+    module Options
+      module_function
+
+      # 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|
+          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|
+          options[:instead_of] = value
+        end
+      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.
+      def resolve_buffer_binding(options, err:)
+        tmp = options[:tmp_file]
+        instead = options[:instead_of]
+        return nil if tmp.nil? && instead.nil?
+
+        if tmp.nil? || instead.nil?
+          err.puts("--tmp-file and --instead-of must appear together")
+          return :usage_error
+        end
+
+        unless File.file?(tmp)
+          err.puts("--tmp-file #{tmp.inspect}: no such file or not readable")
+          return :usage_error
+        end
+
+        Analysis::BufferBinding.new(logical_path: instead, physical_path: tmp)
+      end
+    end
+  end
+end

data/lib/rigor/cli/plugin_command.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "command"
+
 module Rigor
   class CLI
     # `rigor plugin` (singular) — discover and read the plugin source
@@ -44,7 +46,7 @@ module Rigor
     # 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).
-    class PluginCommand
+    class PluginCommand < Command
       USAGE = <<~USAGE
         Usage: rigor plugin <subcommand> [args]
 
@@ -72,12 +74,6 @@ module Rigor
       PLUGINS_ROOT = File.join(GEM_ROOT, "plugins")
       EXAMPLES_ROOT = File.join(GEM_ROOT, "examples")
 
-      def initialize(argv:, out: $stdout, err: $stderr)
-        @argv = argv
-        @out = out
-        @err = err
-      end
-
       # @return [Integer] CLI exit status.
       def run
         subcommand = @argv.shift || "list"

data/lib/rigor/cli/plugins_command.rb

@@ -9,6 +9,7 @@ require_relative "../plugin/services"
 require_relative "../reflection"
 require_relative "../type/combinator"
 require_relative "plugins_renderer"
+require_relative "command"
 
 module Rigor
   class CLI
@@ -60,15 +61,9 @@ module Rigor
     #   the RBS environment without conflict (requires constructing
     #   the Environment, which is heavier than the loader-only
     #   pass this slice does).
-    class PluginsCommand # rubocop:disable Metrics/ClassLength
+    class PluginsCommand < Command # rubocop:disable Metrics/ClassLength
       USAGE = "Usage: rigor plugins [options]"
 
-      def initialize(argv:, out: $stdout, err: $stderr)
-        @argv = argv
-        @out = out
-        @err = err
-      end
-
       # @return [Integer] CLI exit status.
       def run
         options = parse_options

data/lib/rigor/cli/renderable.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "optionparser"
+
+module Rigor
+  class CLI
+    # Output-format dispatch shared by the `--format text|json` renderers.
+    #
+    # Each renderer included this and then implemented `render_text` /
+    # `render_json`; the `render(data, format:)` entry point — route by
+    # the format string, raise one consistent `OptionParser::InvalidArgument`
+    # on anything else — was copied verbatim into every one. Centralising
+    # it keeps the unsupported-format wording and the text/json contract
+    # in a single place as new renderers and formats are added.
+    module Renderable
+      def render(data, format:)
+        case format
+        when "text" then render_text(data)
+        when "json" then render_json(data)
+        else
+          raise OptionParser::InvalidArgument, "unsupported format: #{format}"
+        end
+      end
+    end
+  end
+end

data/lib/rigor/cli/sig_gen_command.rb

@@ -4,6 +4,7 @@ require "optionparser"
 
 require_relative "../configuration"
 require_relative "../sig_gen"
+require_relative "command"
 
 module Rigor
   class CLI
@@ -34,19 +35,13 @@ module Rigor
     # `--params=observed-strict` stays reserved-but-inert until
     # the capability-role catalog ships (rejected with a usage
     # error so the surface stays stable).
-    class SigGenCommand
+    class SigGenCommand < Command
       USAGE = "Usage: rigor sig-gen [options] [paths]"
 
       VALID_MODES = %w[print diff write].freeze
       VALID_PARAM_POLICIES = %w[untyped observed observed-strict].freeze
       VALID_FORMATS = %w[text json].freeze
 
-      def initialize(argv:, out:, err:)
-        @argv = argv
-        @out = out
-        @err = err
-      end
-
       # @return [Integer] CLI exit status.
       def run
         options = parse_options

data/lib/rigor/cli/skill_command.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "command"
+
 require "optparse"
 
 module Rigor
@@ -29,7 +31,7 @@ module Rigor
     #                                as input to a Read tool.
     #
     # `rigor skill` with no subcommand is an alias for `list`.
-    class SkillCommand
+    class SkillCommand < Command
       USAGE = <<~USAGE
         Usage: rigor skill <subcommand> [args]
 
@@ -48,12 +50,6 @@ module Rigor
       # `lib/rigor/cli/skill_command.rb` that is three directories up.
       SKILLS_ROOT = File.expand_path("../../../skills", __dir__)
 
-      def initialize(argv:, out: $stdout, err: $stderr)
-        @argv = argv
-        @out = out
-        @err = err
-      end
-
       # @return [Integer] CLI exit status.
       def run
         subcommand = @argv.shift || "list"

data/lib/rigor/cli/triage_command.rb

@@ -7,6 +7,7 @@ require_relative "../analysis/runner"
 require_relative "../cache/store"
 require_relative "../triage"
 require_relative "triage_renderer"
+require_relative "command"
 
 module Rigor
   class CLI
@@ -18,16 +19,10 @@ module Rigor
     # Read-only and advisory (WD4): never edits config, never
     # writes a baseline. Always exits 0 — it is an inspection
     # command, not a gate (`rigor check` remains the gate).
-    class TriageCommand
+    class TriageCommand < Command
       USAGE = "Usage: rigor triage [options] [paths]"
       DEFAULT_SECTIONS = %i[distribution hotspots hints].freeze
 
-      def initialize(argv:, out:, err:)
-        @argv = argv
-        @out = out
-        @err = err
-      end
-
       # @return [Integer] CLI exit status (always 0).
       def run
         options = parse_options