rigortype 0.4.2 → 0.4.4

data/lib/rigor/cache/incremental_snapshot.rb

@@ -169,7 +169,10 @@ module Rigor
       # file's conditional `def` as certain and a warm run would answer a definer a cold run declines.
       # 37: ADR-119 WD3 — the visibility walk fills `contested_discovered_method_visibilities`, which a pre-37 bundle
       # carries empty.
-      SCHEMA = 37
+      # 38: issue #1898 — the payload gains `effect_plugin_digest`, the plugin effect-fact digest the collections were
+      # stamped under, which a recheck now checks before its served collections reach the envelope pass. A pre-38
+      # blob carries none, so the gate rejects it and the next run is cold.
+      SCHEMA = 38
 
       # The persisted per-file state.
       # `cache` maps an analyzed file to its diagnostics.
@@ -224,11 +227,22 @@ module Rigor
       # Issues #796 / #794 — the run-level rows a narrowed run replays instead of re-deriving; see
       # docs/internal-spec/cache.md § "Run-level rows the snapshot carries" for why exactly these two are
       # fresh under the fingerprint and why no other `.rigor.yml`-level row may join them.
+      # Issue #1898 — `effect_plugin_digest` is {Rigor::Effects::PluginFacts#digest} at the run that collected
+      # `effect_collections` (nil when collection was off). A plugin stamps its attributions and edges into a file's
+      # collection, and `effects_identity` is plugin-blind (it is compared before any plugin loads), so the session
+      # compares this one after the recheck has loaded them.
       Payload = Data.define(:cache, :sources, :digests, :analyzed,
                             :symbol_sources, :ancestry_sources, :symbol_fingerprints,
                             :missing, :class_decls, :constant_decls, :seed_bundles, :plugin_fact_digest,
                             :return_summaries, :param_table,
-                            :effect_collections, :effects_identity, :run_level_rows)
+                            :effect_collections, :effects_identity, :run_level_rows,
+                            :effect_plugin_digest) do
+        # Defaults to nil so a payload built without it (an older caller, a spec fixture) reads as "unknown",
+        # which the session treats as moved.
+        def initialize(effect_plugin_digest: nil, **rest)
+          super
+        end
+      end
 
       # Issues #796 / #794 — the two run-level rows the snapshot carries. `definition_build_failures` is the
       # reported per-class detail list ({Environment::RbsLoader#definition_build_failures}); `hkt_scan_failure`
@@ -260,7 +274,11 @@ module Rigor
       # {EngineSource.process_identity} closes it, and answers nil for a version-pinned tree — which adds no
       # part, so a released gem's fingerprint is byte-identical to the pre-#289 one and its warm snapshots
       # survive the upgrade untouched.
-      def self.fingerprint(configuration:, roots:)
+      #
+      # Issue #1533 — `explain:` is the run's `--explain` flag. It adds `:info` rows to the per-file diagnostics
+      # the snapshot caches, so a snapshot written without it holds none and one written with it holds rows a
+      # plain run must not print. No part for the default, so every plain run's fingerprint is as it was.
+      def self.fingerprint(configuration:, roots:, explain: false)
         bundler_lock, collection_lock = Analysis::RunCacheKey.resolved_lockfile_paths(configuration)
         parts = [
           "engine:#{Rigor::VERSION}:#{SCHEMA}",
@@ -279,14 +297,11 @@ module Rigor
         # dependency edge records, so the whole snapshot goes. Scanned over the configured paths plus the roots'
         # files, the set the run's environment scans; no part when nothing is required, so every other
         # project's fingerprint is as it was.
-        features = Environment::RequiredFeatures.for_configuration(
-          configuration, Analysis::PathExpansion.ruby_files(roots, configuration.exclude_patterns)
-        )
+        features = required_features(configuration, roots)
         parts << "required-features:#{features.join(',')}" unless features.empty?
         # ADR-116 WD5 — the snapshot's per-file rows and seed bundles are only as checked as the run that
         # wrote them ({Inference::DeclarationWalk::Shadow}); nil with the harness off adds no part.
-        shadow = Analysis::ShadowHarness.cache_identity
-        parts << "shadow-harness:#{shadow}" if shadow
+        parts.concat(run_mode_parts(explain))
         Digest::SHA256.hexdigest(parts.join("\x00"))
       rescue StandardError
         # {EngineSource::Unavailable} lands here too, and nil is the answer it requires rather than one it
@@ -297,6 +312,12 @@ module Rigor
         nil
       end
 
+      def self.required_features(configuration, roots)
+        files = Analysis::PathExpansion.ruby_files(roots, configuration.exclude_patterns,
+                                                   base: configuration.exclude_base)
+        Environment::RequiredFeatures.for_configuration(configuration, files)
+      end
+
       # ADR-10 slice 3, issue #1814 — the walked gems' versions: their method catalogue, their refinement table and the
       # constants they bind reach every file's checks, and the lockfile digest above does not cover a project with none.
       # No part for a project that lists no gem, so its fingerprint is what it was.
@@ -314,6 +335,15 @@ module Rigor
       end
       private_class_method :digest_file_if_present
 
+      # The parts naming how the run was asked to behave rather than what it reads: the ADR-116 WD5 shadow harness
+      # (the snapshot's rows are only as checked as the run that wrote them; nil with the harness off) and
+      # `--explain` (#1533).
+      def self.run_mode_parts(explain)
+        shadow = Analysis::ShadowHarness.cache_identity
+        [("shadow-harness:#{shadow}" if shadow), ("explain:true" if explain)].compact
+      end
+      private_class_method :run_mode_parts
+
       # Content-digest every `pre_eval:` file in configuration order, so an edit to one invalidates the snapshot
       # even when it lies outside the analysed paths. A missing file digests as "absent", so creating it counts too.
       def self.digest_pre_eval(paths)
@@ -346,8 +376,20 @@ module Rigor
       end
       private_class_method :digest_signature_paths
 
-      def initialize(root:)
-        @path = File.join(root.to_s, "incremental", "snapshot.bin")
+      # Issue #1867 — one snapshot FILE per fingerprint mode. A run whose fingerprint carries run-mode parts
+      # (`--explain`, the ADR-116 shadow harness) keeps its own file so it neither reads nor overwrites the
+      # plain run's warm snapshot, and the reverse. The plain file name is unchanged. The fingerprint still
+      # carries the mode parts, so the files never cross-serve.
+      def initialize(root:, explain: false)
+        @path = File.join(root.to_s, "incremental", self.class.file_name(explain: explain))
+      end
+
+      # `snapshot.bin` for a plain run; `snapshot-<mode digest>.bin` when {run_mode_parts} is non-empty.
+      def self.file_name(explain: false)
+        parts = run_mode_parts(explain)
+        return "snapshot.bin" if parts.empty?
+
+        "snapshot-#{Digest::SHA256.hexdigest(parts.join("\x00"))[0, 12]}.bin"
       end
 
       attr_reader :path
@@ -406,7 +448,8 @@ module Rigor
           param_table: data[:param_table] || {},
           effect_collections: data[:effect_collections] || {},
           effects_identity: data[:effects_identity],
-          run_level_rows: data[:run_level_rows]
+          run_level_rows: data[:run_level_rows],
+          effect_plugin_digest: data[:effect_plugin_digest]
         )
       end
       private :payload_from
@@ -431,7 +474,8 @@ module Rigor
           param_table: payload.param_table,
           effect_collections: payload.effect_collections,
           effects_identity: payload.effects_identity,
-          run_level_rows: payload.run_level_rows
+          run_level_rows: payload.run_level_rows,
+          effect_plugin_digest: payload.effect_plugin_digest
         )
         # #1507 — every `--incremental` run that analysed anything rewrites this whole blob, so its deflate is
         # on the edit path; see {Store::DEFLATE_LEVEL}.

data/lib/rigor/cli/check_command.rb

@@ -72,6 +72,7 @@ module Rigor
         )
         runner = invocation.runner
         raw_result = invocation.result
+        settle_run_stats(raw_result.stats)
         result = apply_baseline_filter(raw_result, configuration, options)
 
         coverage = compute_coverage(runner, configuration, options)
@@ -180,9 +181,9 @@ module Rigor
       # A plain `--incremental` run the session would answer as a warm recheck and write a slot for. Every other
       # shape declines, and the full path handles it exactly as before: an editor buffer (never saved), `--no-cache`
       # (no store to hold a slot), `--verify-incremental`, a worker pool (the session writes no slot for one: a
-      # worker's plugin reads never reach the process that records them), and `--explain`, which the session
-      # ignores today (#1533) — the slot is keyed without it, so the probe declines rather than answer for a flag
-      # its writer never saw. The rest mirror the plain probe: `--coverage`, `--cache-stats` and the
+      # worker's plugin reads never reach the process that records them), and `--explain` (#1533: the session
+      # writes no slot for it — the slot key has no explain slot — so the probe declines rather than answer for a
+      # flag its writer never saw). The rest mirror the plain probe: `--coverage`, `--cache-stats` and the
       # `RIGOR_*_TRACE` probes each want the full path's own output.
       def incremental_run_hit_eligible?(configuration, options, buffer)
         options.fetch(:incremental) && buffer.nil? &&
@@ -195,6 +196,7 @@ module Rigor
       # The tail {#run_incremental_check} gives a warm run, from the slot's answer: the same banner, baseline
       # filter, output and exit code. No fact-surface note, since a warm run never has one.
       def finalize_incremental_hit(hit, configuration, options)
+        # The slot is written only for a run whose every row still validates, so nothing was re-analyzed.
         report_incremental_run(true, hit.file_count)
         write_incremental_result(hit.result.diagnostics, configuration, options)
       end
@@ -267,8 +269,8 @@ module Rigor
         # Every other file forms the re-analyzed subset, so the run exercises BOTH the subset-analysis path and the
         # cache-serving path.
         subset = analyzed.each_with_index.select { |_, index| index.even? }.map(&:first)
-        incremental = normalize_diagnostics(session.reanalyze_subset(subset))
-        full = normalize_diagnostics(verify_full_diagnostics(configuration, paths))
+        incremental = session.reanalyze_subset(subset).map(&:to_h)
+        full = verify_full_diagnostics(configuration, paths, collect_stats: options.fetch(:stats)).map(&:to_h)
 
         report_verify_incremental(incremental, full, subset_size: subset.size, total: analyzed.size,
                                                      format: options.fetch(:format))
@@ -288,10 +290,11 @@ module Rigor
                         nil
                       else
                         Cache::IncrementalSnapshot.fingerprint(
-                          configuration: configuration, roots: paths || configuration.paths
+                          configuration: configuration, roots: paths || configuration.paths,
+                          explain: options.fetch(:explain)
                         )
                       end
-        snapshot = Cache::IncrementalSnapshot.new(root: cache_root)
+        snapshot = Cache::IncrementalSnapshot.new(root: cache_root, explain: options.fetch(:explain))
         store = incremental_cache_store(configuration, options, cache_root)
         session = Analysis::IncrementalSession.new(
           configuration: configuration, paths: paths,
@@ -300,7 +303,7 @@ module Rigor
           # (CLI `--workers` > `RIGOR_RACTOR_WORKERS` > `parallel.workers:` > 0) so the recheck's closure
           # re-analysis parallelises; the fork pool marshals dependency records back so the graph is sound.
           workers: CheckRunnerFactory.resolve_workers(options, configuration),
-          buffer: buffer
+          buffer: buffer, explain: options.fetch(:explain)
         )
 
         return run_editor_mode_option_b(session, snapshot, fingerprint, configuration, options) if buffer
@@ -309,7 +312,8 @@ module Rigor
         # The banner's file count comes from the session's analyzed set (cold analyses all; a warm recheck's
         # `@analyzed` advances to the current file set), so a dedicated probe Runner + `Dir.glob` is no longer
         # built just to size the banner (recon §3 — the analysis tree was expanded three times per recheck).
-        report_incremental_run(warm, session.analyzed_files.size)
+        # A warm banner reports the recheck's own sets (#1526), which only the session knows.
+        report_incremental_run(warm, session.analyzed_files.size, recheck: session.last_recheck)
         emit_incremental_fact_surface_notes(session)
         write_incremental_cache_stats(session, cache_root, store, options.fetch(:format)) if
           options.fetch(:cache_stats)
@@ -317,9 +321,47 @@ module Rigor
         write_incremental_result(diagnostics, configuration, options)
       end
 
-      def report_incremental_run(warm, file_count)
-        @err.puts("rigor: --incremental #{warm ? 'warm — reused cached diagnostics' : 'cold — full analysis'} " \
-                  "(#{file_count} files)")
+      # #1526 — a warm banner says how many of the analysed files the recheck re-analysed, and why: `changed` is the
+      # edited set, `added` / `removed` the structural delta, and the rest came from the snapshot. A run served from
+      # the run-result slot has no recheck, which means nothing changed: every file is reused.
+      def report_incremental_run(warm, file_count, recheck: nil)
+        body = if warm
+                 "warm — #{warm_recheck_summary(file_count, recheck)}"
+               else
+                 "cold — full analysis (#{pluralize(file_count, 'file')})"
+               end
+        @err.puts("rigor: --incremental #{body}")
+      end
+
+      # The warm clause. `file_count` is the analysed set M (the subset under a path argument); re-analysed files
+      # are M minus the reused set, which includes files invalidated by inferred-parameter changes (ADR-67), not only
+      # the edited closure. View templates are not in M: the recheck re-runs every one, so they are appended as their
+      # own count rather than folded into the file counts.
+      def warm_recheck_summary(file_count, recheck)
+        reused = recheck ? recheck.reused.size : file_count
+        # Current files are either reused or re-analysed (the recheck's `analyze_set`), so the count is taken from
+        # the reused set rather than `affected`, which can also name files that were removed.
+        analyzed = file_count - reused
+        head = "re-analysed #{analyzed} of #{pluralize(file_count, 'file')}"
+        head += " (#{change_counts(recheck).join(', ')})" if recheck && !change_counts(recheck).empty?
+        head += reuse_clause(analyzed, reused)
+        templates = recheck ? recheck.templates : 0
+        templates.positive? ? "#{head}, plus #{pluralize(templates, 'view template')}" : head
+      end
+
+      def change_counts(recheck)
+        { "changed" => recheck.changed.size, "added" => recheck.added.size, "removed" => recheck.removed.size }
+          .filter_map { |label, count| "#{count} #{label}" if count.positive? }
+      end
+
+      def reuse_clause(analyzed, reused)
+        return ", reused all" if analyzed.zero?
+
+        reused.zero? ? "" : ", reused the rest"
+      end
+
+      def pluralize(count, noun)
+        "#{count} #{count == 1 ? noun : "#{noun}s"}"
       end
 
       # The incremental tail, shared by the full path and the ADR-45 WD2 slot hit so a served run prints exactly
@@ -366,17 +408,30 @@ module Rigor
 
       # ADR-88 WD1 — a one-line stderr note when the plugin fact surface (an ADR-9 fact, an ADR-60 producer
       # value, or an `incremental_state_fingerprint` hook) forced a full run: either it CHANGED since the
-      # snapshot (a Sorbet sig edit, a schema change) or a contributing plugin declares NO fingerprint surface
-      # (opaque — a full run every invocation). Both are the sound direction; the note explains why a recheck
-      # was not warm.
+      # snapshot (a Sorbet sig edit, a schema change) or a plugin is opaque to the fingerprint (a full run every
+      # invocation): it contributes types and declares NO fingerprint surface, or a value it declares cannot be
+      # digested. Each opaque plugin's reason is worded per {PluginFactFingerprint::OpaqueReason}, and an
+      # undigestible value is named. Both are the sound direction; the note explains why a recheck was not warm.
       def emit_incremental_fact_surface_notes(session)
-        opaque = session.opaque_plugin_ids
-        unless opaque.empty?
-          @err.puts("rigor: --incremental plugin#{'s' unless opaque.size == 1} #{opaque.sort.join(', ')} " \
-                    "contribute call-site types with no incremental fingerprint surface; the snapshot cannot " \
-                    "be reused (full analysis every run).")
+        reasons = session.opaque_reasons
+        surfaceless = reasons.keys.select { |id| reasons.fetch(id).kind == :no_surface }.sort
+        unless surfaceless.empty?
+          many = surfaceless.size > 1
+          @err.puts("rigor: --incremental plugin#{'s' if many} #{surfaceless.join(', ')} " \
+                    "contribute#{'s' unless many} call-site types with no incremental fingerprint surface; " \
+                    "the snapshot cannot be reused (full analysis every run).")
+        end
+        reasons.each do |id, reason|
+          next if reason.kind == :no_surface
+
+          @err.puts("rigor: --incremental #{reason.describe(id)}; the snapshot cannot be reused " \
+                    "(full analysis every run).")
+        end
+        if session.fact_store_unreadable?
+          @err.puts("rigor: --incremental the plugin fact store could not be read; the snapshot cannot be reused " \
+                    "(full analysis every run).")
         end
-        return unless session.fact_surface_invalidated? && opaque.empty?
+        return unless session.fact_surface_invalidated? && !session.opaque_fact_surface?
 
         @err.puts("rigor: --incremental plugin fact surface changed since the snapshot; ran a full analysis.")
       end
@@ -388,8 +443,10 @@ module Rigor
       def write_incremental_cache_stats(session, cache_root, store, format)
         write_cache_stats(cache_root, store, format)
         status =
-          if !session.opaque_plugin_ids.empty?
-            "opaque (#{session.opaque_plugin_ids.sort.join(', ')})"
+          if session.opaque_fact_surface?
+            verdicts = session.opaque_reasons.map { |id, reason| "#{id}: #{reason.summary}" }
+            verdicts << "fact store: could not be read" if session.fact_store_unreadable?
+            "opaque (#{verdicts.join('; ')})"
           elsif session.fact_surface_invalidated?
             "changed — snapshot invalidated"
           else
@@ -398,38 +455,72 @@ module Rigor
         side_output(format).puts("  plugin fact surface: #{status}")
       end
 
-      def verify_full_diagnostics(configuration, paths)
-        runner = Analysis::Runner.new(configuration: configuration, cache_store: nil)
+      def verify_full_diagnostics(configuration, paths, collect_stats: true)
+        runner = Analysis::Runner.new(configuration: configuration, cache_store: nil, collect_stats: collect_stats)
         (paths ? runner.run(paths) : runner.run).diagnostics
       end
 
-      def normalize_diagnostics(diagnostics)
-        diagnostics.map(&:to_h).sort_by do |hash|
-          [hash["path"].to_s, hash["line"].to_i, hash["column"].to_i, hash["rule"].to_s, hash["message"].to_s]
-        end
-      end
-
+      # Issue #1542 — the rows are compared as a multiset over every field each row carries, so two rows that tie on
+      # the sort key but differ in severity, or a duplicated row, are a set mismatch and never a silent 0/0. Only when
+      # the multisets agree is the order compared, and an order mismatch is reported as its own failure, with the first
+      # index at which the two lists diverge, so a set regression and an order regression stay distinguishable.
+      #
       # The OK line follows the same rule as the other side outputs (#493) — stdout under `text`, stderr
       # under a machine format. The FAILED branch below has always gone to stderr: it is a failure
       # report, and a run that produced one has no valid document to protect anyway.
       def report_verify_incremental(incremental, full, subset_size:, total:, format: "text")
-        if incremental == full
-          side_output(format).puts("rigor: --verify-incremental OK — incremental " \
-                                   "(#{subset_size}/#{total} files re-analyzed, rest from cache) " \
-                                   "matches full (#{full.size} diagnostics)")
-          return 0
+        return report_verify_set_mismatch(incremental, full) unless incremental.tally == full.tally
+        return report_verify_order_mismatch(incremental, full) unless incremental == full
+
+        side_output(format).puts("rigor: --verify-incremental OK — incremental " \
+                                 "(#{subset_size}/#{total} files re-analyzed, rest from cache) " \
+                                 "matches full (#{full.size} diagnostics)")
+        0
+      end
+
+      # The rows one side has more of than the other, counted by multiplicity: [x, x, y] against [x, y, y] has one
+      # extra x on the left and one extra y on the right.
+      def multiset_difference(left, right)
+        budget = right.tally
+        left.reject do |row|
+          next false unless budget.fetch(row, 0).positive?
+
+          budget[row] -= 1
+          true
         end
+      end
 
-        only_incremental = incremental - full
-        only_full = full - incremental
+      def report_verify_set_mismatch(incremental, full)
+        only_incremental = multiset_difference(incremental, full)
+        only_full = multiset_difference(full, incremental)
         @err.puts("rigor: --verify-incremental FAILED — incremental and full diagnostics differ.")
         @err.puts("  incremental-only: #{only_incremental.size}, full-only: #{only_full.size}")
         (only_incremental + only_full).first(10).each do |hash|
-          @err.puts("    #{hash['path']}:#{hash['line']}:#{hash['column']}: [#{hash['rule']}] #{hash['message']}")
+          @err.puts("    #{diagnostic_location(hash)}")
         end
         1
       end
 
+      def report_verify_order_mismatch(incremental, full)
+        index = (0...incremental.size).find { |i| incremental[i] != full[i] }
+        @err.puts("rigor: --verify-incremental FAILED — same set, different order.")
+        @err.puts("  incremental and full report the same #{full.size} diagnostics in a different order; " \
+                  "first divergence at index #{index}:")
+        @err.puts("    incremental: #{diagnostic_location(incremental[index])}")
+        @err.puts("    full:        #{diagnostic_location(full[index])}")
+        1
+      end
+
+      # Severity, source family and the optional fields a row may carry, so two rows that differ only in one of them
+      # never print as the same line.
+      def diagnostic_location(hash)
+        extra = %w[receiver_type method_name project_definition_site].filter_map do |key|
+          " #{key}=#{hash[key]}" if hash.key?(key)
+        end
+        "#{hash['path']}:#{hash['line']}:#{hash['column']}: #{hash['severity']} [#{hash['rule']}] " \
+          "(#{hash['source_family']}) #{hash['message']}#{extra.join}"
+      end
+
       # ADR-22 slice 5 — the `--baseline-strict` CI gate. When the flag is set, ANY baseline drift fails the run — not
       # only excess drift (a bucket over threshold, which already fails via the surfaced diagnostics) but also DEFICIT
       # drift (`actual < count`: the baseline has grown looser than the code and should be regenerated). A no-op, with a
@@ -689,6 +780,7 @@ module Rigor
         data = data.dup
         data["plugins"] = inject_treat_all_as_inline_rbs(Array(data["plugins"]))
         Configuration.new(Configuration::DEFAULTS.merge(data), effects_key_present, target_ruby_key_present)
+                     .with_exclude_base(path && File.exist?(path) ? File.dirname(path) : nil)
       end
 
       # ADR-50 § WD2 — applies the `--bleeding-edge[=ids]` / `--no-bleeding-edge` CLI selection over the configured
@@ -725,6 +817,13 @@ module Rigor
         end
       end
 
+      # Issue #1529 — reads the run's peak RSS straight after the analysis, before coverage or any output, so the
+      # figure the summary prints (and the JSON `stats` block carries) covers the analysis alone. A nil `stats`
+      # (`--no-stats`, or a run served from a cache) reads nothing.
+      def settle_run_stats(stats)
+        stats&.peak_rss_bytes
+      end
+
       # Emits the {Analysis::RunStats} summary to STDERR so it doesn't interleave with the diagnostic stream (text or
       # JSON) on STDOUT. JSON consumers can pipe stdout cleanly; interactive users still see the summary on their tty.
       def write_run_stats(stats)

data/lib/rigor/cli/docs_command.rb

@@ -78,7 +78,7 @@ module Rigor
 
       def run_index
         if File.file?(LLMS_INDEX)
-          @out.write(File.read(LLMS_INDEX))
+          @out.write(File.read(LLMS_INDEX, encoding: Encoding::UTF_8))
           0
         else
           run_list(nil)
@@ -115,11 +115,12 @@ module Rigor
         doc = resolve_doc(name)
         return doc if doc.is_a?(Integer) # error status, already reported
 
-        # ASCII-only provenance header: the doc body is read with the external encoding (US-ASCII under a C locale), so
-        # a UTF-8 header would set the output buffer to UTF-8 and clash with the body.
+        # The bundled page is UTF-8 by contract, so it is read as UTF-8 explicitly: under a C or POSIX locale the
+        # process default external encoding is US-ASCII, and a non-ASCII body would otherwise raise in `gsub`.
+        # The provenance header stays ASCII-only so it never disagrees with the rest of the output.
         @out.puts("<!-- rigor docs #{doc.fetch(:name)} (rigortype #{Rigor::VERSION}, offline) -->")
         @out.puts
-        @out.write(DocLinks.rewrite(File.read(doc.fetch(:path)), from: doc.fetch(:path)))
+        @out.write(DocLinks.rewrite(File.read(doc.fetch(:path), encoding: Encoding::UTF_8), from: doc.fetch(:path)))
         0
       end
 

data/lib/rigor/cli/lens_command.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+
+require_relative "command"
+require_relative "options"
+require_relative "check_runner_factory"
+require_relative "../configuration"
+require_relative "../lens"
+
+module Rigor
+  class CLI
+    # `rigor lens FILE...` — a declaration map of the files with type provenance, computed as `rigor check`
+    # 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).
+        root = Dir.pwd
+        workers = CheckRunnerFactory.resolve_workers(options, configuration)
+        outcome = Lens::Run.new(configuration: configuration, root: root, arguments: @argv, workers: workers).call
+        document = Lens::Document.new(outcome: outcome, configuration: configuration, root: root,
+                                      config_path: config_path).to_h
+        @err.puts("rigor lens: #{outcome.warm ? 'warm' : 'cold'} — #{@argv.size} target(s)")
+        render(document, options.fetch(:format))
+        outcome.targets.any? { |target| target.status == "ok" } ? 0 : 1
+      end
+
+      private
+
+      def parse_options
+        options = { format: "text", config: nil, workers: nil }
+        OptionParser.new do |opts|
+          opts.banner = USAGE
+          opts.on("--format=FORMAT", "Output format: text (default) or json") { |value| options[:format] = value }
+          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])
+        return usage_error("no FILE given") if @argv.empty?
+
+        options
+      rescue OptionParser::ParseError => e
+        usage_error(e.message)
+      end
+
+      def usage_error(message)
+        @err.puts("rigor lens: #{message}")
+        @err.puts(USAGE)
+        nil
+      end
+
+      def render(document, format)
+        if format == "json"
+          @out.puts(JSON.generate(document))
+        else
+          TextRenderer.new(document, @out).render
+        end
+      end
+
+      # The text rendering for agents and people. Its layout is not a contract; the `LINE:HASH` anchor token is.
+      class TextRenderer
+        def initialize(document, out)
+          @document = document
+          @out = out
+          @members = document["members"].each_with_object(Hash.new { |hash, key| hash[key] = [] }) do |member, index|
+            member["sites"].each { |key| index[key] << member }
+          end
+        end
+
+        def render
+          @document["files"].each { |file| render_file(file) }
+        end
+
+        private
+
+        def render_file(file)
+          unless file["status"] == "ok"
+            @out.puts("#{file['argument']}  #{file['status']}: #{file['reason']}")
+            return
+          end
+
+          omitted = file["omissions"].empty? ? "" : "  (#{file['omissions'].size} omitted)"
+          @out.puts("#{file['path']}  #{file['digest']}#{omitted}")
+          file["sites"].each { |site| render_site(site) }
+          file["omissions"].each do |omission|
+            @out.puts("  omitted #{omission['kind']} #{omission['name']} (line #{omission.dig('span', 'start_line')})")
+          end
+          file["diagnostics"].each do |diagnostic|
+            @out.puts("  #{diagnostic['line']}:#{diagnostic['column']} #{diagnostic['severity']} " \
+                      "#{diagnostic['message']} [#{diagnostic['rule']}]")
+          end
+        end
+
+        def render_site(site)
+          case site["kind"]
+          when "class", "module" then @out.puts("  #{site['anchor']}  #{site['kind']} #{site['name']}")
+          else
+            @members[site["key"]].each { |member| render_member(site, member) }
+          end
+        end
+
+        def render_member(site, member)
+          separator = member["scope"] == "singleton" ? "." : "#"
+          if member["overloads"].empty?
+            elsewhere = member["also_defined_at"].map { |entry| "#{entry['path']}:#{entry['line']}" }
+            @out.puts("  #{site['anchor']}  #{site['owner']}#{separator}#{member['name']}  " \
+                      "[#{member['basis']}#{"; also #{elsewhere.join(', ')}" unless elsewhere.empty?}]")
+          end
+          member["overloads"].each do |overload|
+            signature = overload["rbs"] || "(signature unavailable: #{unavailable_reasons(overload).join(', ')})"
+            @out.puts("  #{site['anchor']}  #{site['owner']}#{separator}#{member['name']}: #{signature}  " \
+                      "[#{member['basis']}#{provenance_note(overload)}]")
+          end
+        end
+
+        def provenance_note(overload)
+          provenances = ([overload["return"]] + (overload["params"] || []).map { |param| param["type"] })
+                        .filter_map { |slot| slot["provenance"] }.uniq
+          provenances.empty? ? "" : " #{provenances.join('+')}"
+        end
+
+        def unavailable_reasons(overload)
+          ([overload["return"]] + (overload["params"] || []).map { |param| param["type"] })
+            .filter_map { |slot| slot["reason"] }.uniq
+        end
+      end
+    end
+  end
+end

data/lib/rigor/cli/lsp_command.rb

@@ -53,8 +53,11 @@ module Rigor
       def build_server(writer:, 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`.
-        project_context = LanguageServer::ProjectContext.new(configuration: configuration)
+        # Invalidated by `workspace/didChangeWatchedFiles` and `workspace/didChangeConfiguration`; every save round
+        # also re-reads the configuration (the loader below) and re-baselines when its inputs moved (#1613).
+        project_context = LanguageServer::ProjectContext.new(
+          configuration: configuration, configuration_loader: -> { Configuration.load(config_path) }
+        )
         # Single source of truth for buffer state — threaded to Server + all three providers.
         buffer_table = LanguageServer::BufferTable.new
         debouncer = LanguageServer::Debouncer.new

data/lib/rigor/cli/mcp_command.rb

@@ -12,7 +12,7 @@ module Rigor
     # Starts a long-running MCP (Model Context Protocol) server over stdio. The server exposes Rigor's analysis tools as
     # MCP tool calls over a newline-delimited JSON-RPC 2.0 stream. See ADR-33.
     #
-    # Slice 1 ships the stdio transport with seven read-only tools: rigor_check, rigor_type_of, rigor_triage,
+    # The stdio transport serves eight read-only tools: rigor_check, rigor_type_of, rigor_triage, rigor_lens,
     # rigor_annotate, rigor_sig_gen, rigor_explain, rigor_coverage.
     class McpCommand < Command
       USAGE = "Usage: rigor mcp [options]"

data/lib/rigor/cli/skill_command.rb

@@ -128,7 +128,7 @@ module Rigor
 
         @out.puts(render_print_header(skill))
         @out.puts
-        @out.write(File.read(skill.fetch(:path)))
+        @out.write(File.read(skill.fetch(:path), encoding: Encoding::UTF_8))
         0
       end
 
@@ -145,14 +145,14 @@ module Rigor
 
         @out.puts(render_print_header(skill))
         @out.puts
-        @out.write(File.read(skill.fetch(:path)))
+        @out.write(File.read(skill.fetch(:path), encoding: Encoding::UTF_8))
 
         reference_files(skill).each do |ref|
           @out.puts
           @out.puts
           @out.puts("<!-- ===== references/#{File.basename(ref)} (bundled with rigortype #{Rigor::VERSION}) ===== -->")
           @out.puts
-          @out.write(File.read(ref))
+          @out.write(File.read(ref, encoding: Encoding::UTF_8))
         end
         0
       end