rigortype 0.3.9 → 0.4.0

data/lib/rigor/analysis/dependency_recorder.rb

@@ -126,6 +126,29 @@ module Rigor
         [result, capture.snapshot]
       end
 
+      # Issue #992 — runs the block with its reads DETACHED from the current consumer (and from any enclosing
+      # capture) and returns `[block_result, read_set]`, so a caller that learns only afterwards whether its
+      # answer depended on those reads can {replay} them or drop them. `call.wrong-arity` reads a class's whole
+      # envelope bucket to decide a call that turns out to fit, and recording that as a file-level ancestry
+      # edge would make every correct call on a project class re-check on any edit to the class's files.
+      # Returns a nil read set when no recording is active.
+      def withhold
+        previous = Thread.current[KEY]
+        return [yield, nil] if previous.nil?
+
+        previous_captures = Thread.current[CAPTURE_KEY]
+        capture = Capture.new
+        Thread.current[KEY] = Accumulator.new(previous.consumer)
+        Thread.current[CAPTURE_KEY] = [capture]
+        begin
+          result = yield
+        ensure
+          Thread.current[KEY] = previous
+          Thread.current[CAPTURE_KEY] = previous_captures
+        end
+        [result, capture.snapshot]
+      end
+
       # ADR-84 WD2 — replays a {ReadSet} into the current consumer's accumulator as if each read happened
       # here, applying the same per-consumer self-read filter as {read_site}, and tees into every active
       # capture so an enclosing capture window stays transitive when a memo hit substitutes for a body walk.

data/lib/rigor/analysis/fact_store.rb

@@ -21,8 +21,17 @@ module Rigor
         # #775 — a target is an immutable value keyed by its name, and the local target is built on every
         # binding (`Scope#with_local` invalidates through it) and every local-fact read: ~350k times on
         # the lib self-check for a few thousand distinct names. One shared instance per name.
+        #
+        # #1055 — the table is a class ivar holding an unshareable Hash, and a non-main Ractor may neither
+        # write one nor read one. A pool worker therefore pays the allocation instead of sharing the
+        # instance: the interning is a per-process ALLOCATION saving, never an identity contract (`Target`
+        # is a `Data` value and compares by value), so declining it changes nothing a caller can observe.
+        # The guard is a C-level predicate on the hot path, which is what keeps the sequential run's
+        # saving intact.
         def self.local(name)
           name = name.to_sym
+          return new(kind: :local, name: name) unless Ractor.main?
+
           @local_targets[name] ||= new(kind: :local, name: name)
         end
         @local_targets = {}

data/lib/rigor/analysis/incremental.rb

@@ -120,6 +120,32 @@ module Rigor
         appeared.freeze
       end
 
+      # Issue #1120 — the method names whose refinements moved in this edit: a `[refined class, method, refining
+      # module]` entry that appeared in, or vanished from, any file in `paths`. A consumer whose
+      # `call.undefined-method` answer consulted the refinement table recorded a `refinement:<method>` edge
+      # whichever way it answered, because the answer is a function of the whole project's refinements of that
+      # name. `paths` MUST include removed files, whose whole before-table vanished. `before` / `after` map a
+      # path to that file's `{refined class => {method => [modules]}}` table (nil when it refines nothing).
+      def changed_refinement_names(paths, before, after)
+        moved = Set.new
+        paths.each do |path|
+          entries_before = refinement_entries(before[path])
+          entries_after = refinement_entries(after[path])
+          (entries_before ^ entries_after).each { |(_refined, method_name, _module)| moved << method_name }
+        end
+        moved.freeze
+      end
+
+      def refinement_entries(table)
+        entries = Set.new
+        table&.each do |refined, methods|
+          methods.each do |method_name, modules|
+            modules.each { |refining| entries << [refined, method_name, refining] }
+          end
+        end
+        entries
+      end
+
       # Issue #639 — the SYMMETRIC reading of {appeared_classes}: the names whose declaration in a file
       # appeared OR VANISHED. Appearance alone answered the miss side, which was the only side recording a
       # `class:` edge; a bare reference that RESOLVED now records one too, and what invalidates it is the

data/lib/rigor/analysis/incremental_session.rb

@@ -162,7 +162,11 @@ module Rigor
         runner = build_runner(record_dependencies: true)
         diagnostics = run_runner(runner).diagnostics
         @last_runner = runner # ADR-88 WD1 — the post-hoc fact-surface fingerprint reads this prepared registry.
-        @analyzed = runner.analyzed_files
+        # #392 — the template units are deliberately NOT in the analysed set. `Runner#target_files`
+        # re-analyses every unit on every run, so a unit must never be reused from the per-file cache and
+        # must never read as a file that VANISHED from the project on the next recheck (which is what
+        # `previous - current` would say, `current_files` being a `.rb` expansion).
+        @analyzed = runner.analyzed_files - runner.template_unit_paths
         @seed_bundles = runner.seed_bundles # ADR-85 WD2 — the freshly built bundle set for the next run.
         absorb_dependency_graph(runner)
         @return_summaries = runner.return_summaries # ADR-89 WD2 — the full-run behavioural surface.
@@ -283,12 +287,24 @@ module Rigor
         symbol_pairs = behaviourally_unstable_pairs(changed_pairs, unstable, scan_index) | param_pairs
         base = dependents_base(unstable, symbol_pairs)
         closure = base | changed.to_set | added.to_set |
-                  negative_affected(scan, removed, new_fps, new_class_decls, new_constant_decls)
+                  negative_affected(scan, removed, new_fps, new_class_decls, new_constant_decls, summary)
         closure = param_seed_closure(closure, param_files)
         removed.each { |path| closure |= @dependents[path] || Set.new }
         closure.freeze
       end
 
+      # Issue #1367 — every file whose last result holds a `global.*` diagnostic re-checks on any recheck. What
+      # exempts such a write is a fact of the whole program — an alias, or a `write` / `to_str` / `to_int` / hatch
+      # defined in any spelling on any receiver, a rewritten ancestor, a mixin — which no name-keyed edge can
+      # follow, so a stale report would outlive the edit that exempts it. Such files are rare, so this costs little.
+      # A file the census silenced is not re-checked when the exemption goes away: that stale answer misses a
+      # report, it never makes one.
+      def global_write_reporters
+        @cache.each_with_object(Set.new) do |(path, diagnostics), reporters|
+          reporters << path if diagnostics.any? { |diagnostic| diagnostic.rule.to_s.start_with?("global.") }
+        end
+      end
+
       # ADR-67 WD6c lift — the seed-invalidated callees' own contribution to the closure: the files
       # themselves, plus — on a pre-slice-4 snapshot with no symbol edges, where the pairs' symbol fan-out
       # found nothing — their file-level dependents (wider, always sound).
@@ -828,7 +844,9 @@ module Rigor
       # a prior missed lookup, and (issue #639) because a class DECLARATION appeared or vanished. Maps each
       # appeared `"ClassName#method"` to the negative-dependency key it would satisfy (`toplevel:foo` for a
       # top-level def, `method:C#m` otherwise), then unions the recorded negative-dependents of those keys.
-      def negative_affected(changed, removed, new_fingerprints, new_class_decls, new_constant_decls)
+      # Issue #1120 — plus the consumers of any refinement name the edit moved ({#refinement_affected}). Issue #1367 —
+      # and every file whose last result holds a `global.*` diagnostic ({#global_write_reporters}).
+      def negative_affected(changed, removed, new_fingerprints, new_class_decls, new_constant_decls, summary = nil)
         appeared_methods = Incremental.appeared_symbols(changed, @symbol_fingerprints, new_fingerprints)
         # Issue #639 — a class DISAPPEARING satisfies the `class:` kind too, now that a resolved bare
         # reference records the edge and not only a failed one; removed files join the diff for it.
@@ -844,7 +862,21 @@ module Rigor
         keys = appeared_methods.map { |symbol| negative_key_for(symbol) }
         keys.concat(moved_classes.map { |klass| "class:#{klass.split('::').last}" })
         keys.concat(moved_constants.map { |name| "constant:#{name.split('::').last}" })
-        Incremental.negative_closure(keys, @negative_dependents)
+        Incremental.negative_closure(keys, @negative_dependents) | refinement_affected(changed + removed, summary) |
+          global_write_reporters
+      end
+
+      # Issue #1120 — the consumers whose `call.undefined-method` answer read the refinement table for a method
+      # name whose refinements moved in this edit. The before-state is each file's seed bundle (the per-file
+      # table the last run recorded), the after-state the scan's per-file tables. A refine body is not a class's
+      # method, so neither the symbol fingerprints nor the appeared-symbol diff above sees it.
+      def refinement_affected(paths, summary)
+        after = (summary && summary[:refinements]) || {}
+        before = paths.to_h { |path| [path, @seed_bundles.dig(path, :refinements)] }
+        names = Incremental.changed_refinement_names(paths, before, after)
+        return Set.new if names.empty?
+
+        Incremental.negative_closure(names.map { |name| "refinement:#{name}" }, @negative_dependents)
       end
 
       # The qualified class/module names declared in the pre-parsed `index` (shared with

data/lib/rigor/analysis/project_scan.rb

@@ -16,13 +16,23 @@ module Rigor
     # are NOT visible until the owner invalidates the scan — typically via `workspace/didChangeWatchedFiles`.
     # This is the same trade-off the LSP made when slice 7 cached only the `Environment`; extending the cache
     # to the pre-pass outputs preserves the contract.
+    #
+    # `template_units` (#1038) is the one slot a consumer does not adopt verbatim. The rest of the snapshot
+    # is reused as it stands until the owner invalidates it; the template index is handed to
+    # `TemplateUnits.collect(previous:)`, which re-expands the claimed globs and revalidates each template
+    # against the filesystem, so a template edited, added or deleted on disk is seen on the next publish
+    # even though the snapshot itself did not move. What the carry saves is the plugin transform — for ERB
+    # (#393) an Erubi compile of every view in the project, otherwise paid per keystroke. The index is
+    # always built WITHOUT a buffer binding, so the shared snapshot never holds a unit compiled from an
+    # editor's in-flight bytes.
     ProjectScan = Data.define(
       :plugin_registry,
       :dependency_source_index,
       :synthetic_method_index,
       :project_patched_methods,
       :plugin_prepare_diagnostics,
-      :pre_eval_diagnostics
+      :pre_eval_diagnostics,
+      :template_units
     )
   end
 end

data/lib/rigor/analysis/reachability/plugin_roots.rb

@@ -83,7 +83,6 @@ module Rigor
         # Loads the project's configured plugins, runs every `#prepare`, and returns the union of every
         # published `:reachability_roots` and `:reachability_references` fact.
         #
-        # @param configuration — the loaded project configuration.
         # @param plugin_requirer — how a plugin gem is brought into the process, called with the gem name. The
         #   same seam `Analysis::Runner` exposes, so a spec can register a plugin class without publishing a
         #   gem.

data/lib/rigor/analysis/reachability/scan_cache.rb

@@ -36,6 +36,7 @@ module Rigor
           File.expand_path("scan.rb", __dir__),
           File.expand_path(__FILE__)
         ].freeze
+        Ractor.make_shareable(SOURCE_FILES)
 
         # A file modified within this window of the recording instant is computed but never
         # recorded — the FileDigest racy-write guard, one tier simpler because a refused signature

data/lib/rigor/analysis/rule_catalog.rb

@@ -656,6 +656,90 @@ module Rigor
           since: "0.1.2"
         ),
 
+        CheckRules::RULE_GLOBAL_WRITE_TYPE_MISMATCH => Entry.new(
+          id: CheckRules::RULE_GLOBAL_WRITE_TYPE_MISMATCH,
+          summary: "A special global is assigned a literal its setter rejects (TypeError at runtime).",
+          fires_when: [
+            "The write is `$g = literal` to a special whose setter checks the value: `$/` / `$-0`, `$,` and " \
+            "`$\\` (a String or nil), `$;` / `$-F` (a String, a Regexp, nil, or an object with `to_str`), `$~` " \
+            "(a MatchData or nil), `$0` / `$PROGRAM_NAME` (a String or an object with `to_str`), `$.` (an " \
+            "Integer, a Float, or an object with `to_int`), `$-i` (a String, nil, false, or an object with " \
+            "`to_str`), and `$stdout` / `$>` / `$stderr` (an object that responds to `write`, ADR-117 WD2).",
+            "The value is a literal node — an Integer, Float, Rational or imaginary literal, a String, Symbol " \
+            "or Regexp literal (interpolated or not), an Array or Hash literal, or `nil` / `true` / `false`, " \
+            "parenthesised or not — whose class the setter does not take: `$/ = 1`, `$/ = /x/`, `$~ = \"x\"`, " \
+            "`$0 = nil`, `$. = \"3\"`, `$stdout = 1`.",
+            "Where the setter also converts (`to_str`, `to_int`) or asks for `write`, the literal's object " \
+            "cannot answer that method: RBS gives its class neither the method nor a `method_missing` / " \
+            "`respond_to_missing?` / `respond_to?` of its own, and the program defines none of them anywhere.",
+            "The envelope is the interpreter's setter, not the global's RBS declaration: `$/ = /x/` fires " \
+            "although `$;` takes a Regexp."
+          ],
+          does_not_fire_when: [
+            "The special's setter accepts every value: `$stdin` (never checked, ADR-117 WD2), `$_`, `$VERBOSE`, " \
+            "`$DEBUG`, `$=`; nor `$@`, whose setter depends on whether `$!` is set.",
+            "The value is not a literal — a variable, a method call, a constant, a conditional — whatever its " \
+            "inferred type: a class RBS declares without `write` or `to_str` does not prove the object lacks it.",
+            "RBS gives the literal's class the method or a hatch of its own (a `sig/` reopening or `include` " \
+            "counts).",
+            "The program — any project or `pre_eval:` file — defines the method or a `method_missing` / " \
+            "`respond_to_missing?` / `respond_to?` anywhere, in any spelling (`def`, `define_method`, " \
+            "`define_singleton_method`, `alias`, `alias_method`, `attr_*`, a delegation macro, a string `eval`, " \
+            "the same through `send`) and on any receiver, or defines a method whose name no literal spells (a " \
+            "computed `define_method` or `send` name, a string `eval` whose code is not a plain literal, a name " \
+            "whose bytes are not valid in its encoding). " \
+            "This is blanket: no census of where a definition lands can be complete, so the literal of every " \
+            "class declines, whatever the definition's owner.",
+            "An ancestor's surface is rewritten from outside (`Integer.include(M)`, `Object.include(M)`, a string " \
+            "`class_eval`), or a top-level `include` / `prepend` / `extend`, or an ancestor's `include`, names a " \
+            "module RBS does not rule out.",
+            "For `$stdout` / `$>` / `$stderr`, a refinement that may add `write`, to any class, and a `using` in " \
+            "effect at the write. Which class it refines is not followed. The `to_str` / `to_int` conversions, and a " \
+            "refined `respond_to_missing?` / `respond_to?`, ignore refinements, so those still fire.",
+            "Any project or `pre_eval:` file aliases the special (`alias $stdout $out`, on either side).",
+            "The write is `$g op= v`, `$g ||= v`, `$g &&= v`, a multiple-assignment target, a `for` index, or a " \
+            "`rescue => $g` reference: their value is not type-checked.",
+            "The write sits in the dead arm of a decidable version guard. Other code that never runs (`if " \
+            "false`, after `return`) is not recognised, and a write there still fires."
+          ],
+          suppression: "`# rigor:disable global.write-type-mismatch` on the write.",
+          severity_authored: :error,
+          severity_by_profile: { lenient: :warning, balanced: :error, strict: :error },
+          # A literal's class is exact, the setter's envelope is the running interpreter's, and every way a program can
+          # give the object the method the setter asks for declines; the write then raises every time it runs.
+          evidence_tier: :high,
+          since: "0.4.0"
+        ),
+
+        CheckRules::RULE_GLOBAL_READONLY_WRITE => Entry.new(
+          id: CheckRules::RULE_GLOBAL_READONLY_WRITE,
+          summary: "A read-only special global is written (NameError at runtime).",
+          fires_when: [
+            "The write is `$g = value`, `$g op= value`, or a target of a multiple assignment (`$g, x = ...`, " \
+            "`*$g`) — forms that always write — to a special Ruby defines read-only: `$!`, `$$`, `$?`, `$<`, " \
+            "`$FILENAME`, `$*`, `$:` / `$LOAD_PATH` / `$-I`, `$\"` / `$LOADED_FEATURES`, `$-W`, `$-p`, `$-l`, " \
+            "`$-a`.",
+            "Whatever the value: the setter raises `NameError` (`$! is a read-only variable`) before it " \
+            "looks at it."
+          ],
+          does_not_fire_when: [
+            "The write is `$g ||= v` or `$g &&= v`, which writes only when the current value is falsy " \
+            "(truthy): `$LOAD_PATH ||= []` never writes.",
+            "The write is a `for` index or a `rescue => $g` reference.",
+            "Any project or `pre_eval:` file aliases the special (`alias $! $err`, on either side), which can " \
+            "make the name another variable.",
+            "Mutating the value is not a write: `$LOAD_PATH << dir` and `$LOADED_FEATURES.delete(f)` stay silent.",
+            "The write sits in the dead arm of a decidable version guard. Other code that never runs is not " \
+            "recognised, and a write there still fires."
+          ],
+          suppression: "`# rigor:disable global.readonly-write` on the write.",
+          severity_authored: :error,
+          severity_by_profile: { lenient: :error, balanced: :error, strict: :error },
+          # Syntactic: the name alone decides it, and the write raises every time it runs.
+          evidence_tier: :high,
+          since: "0.4.0"
+        ),
+
         CheckRules::RULE_SUPPRESSION_UNKNOWN_RULE => Entry.new(
           id: CheckRules::RULE_SUPPRESSION_UNKNOWN_RULE,
           summary: "A `# rigor:disable[-file]` comment names a rule that does not exist.",
@@ -896,6 +980,48 @@ module Rigor
           since: "0.3.4"
         ),
 
+        CheckRules::RULE_CONTRADICTING_SIGNATURE => Entry.new(
+          id: CheckRules::RULE_CONTRADICTING_SIGNATURE,
+          summary: "Two declarations of one method provably contradict: no value or call satisfies both.",
+          fires_when: [
+            "A method is declared both in the project's `sig/` and by an inline `# @rbs` / `#:` " \
+            "annotation, and the return or a parameter every call must pass holds two proven-disjoint " \
+            "types — distinct literals, a literal outside such a class, or two classes written absolutely " \
+            "whose RBS comes from Ruby core or the stdlib, neither an RBS ancestor of the other " \
+            "(`::String` against `::Integer`) — or the two keyword-free declarations accept " \
+            "positional counts that cannot meet, or one requires a keyword the other cannot take in any " \
+            "form. Several overloads are paired by correspondence, never by order. Positioned at the " \
+            "`.rbs` member; Rigor reads that declaration.",
+            "A member-level `%a{rigor:v1:return: …}` or `%a{rigor:v1:param: …}` refinement is proven " \
+            "disjoint from the type its own member declares, in every overload it applies to " \
+            "(`rigor:v1:return: positive-int` on `-> String`)."
+          ],
+          does_not_fire_when: [
+            "One declaration refines the other (`String` against `non-empty-string`, `Symbol` against " \
+            "`:asc | :desc`, `bool` against `TrueClass`): the two merge to the more precise one, silently.",
+            "Either side is `untyped`, `void` or `top` in that position — consistent with everything.",
+            "Rigor cannot prove the two contradict: a module or interface on either side, a class the " \
+            "project declares (in `sig/`, inline or only in Ruby), a gem's class, any relative class name, " \
+            "two element types of one generic class, a type alias, `self`, a type variable, a proc, an " \
+            "optional or rest position, any block position, overloads that do not pair one to one, or " \
+            "differently shaped parameter lists that still overlap. The " \
+            "inline signature is then dropped and reported as `source-rbs-annotation-not-honoured` (info).",
+            "A refinement is written on one overload rather than on the member: call sites do not honour it.",
+            "Two `.rbs` files declare the same method (that fails the class's definition build, " \
+            "`rbs.coverage.definition-build-failed`), or a project `.rbs` collides with bundled RBS " \
+            "(the file is quarantined, `rbs.coverage.quarantined-signature`)."
+          ],
+          suppression: "`disable: [\"rbs.contradicting-signature\"]` in `.rigor.yml`, or a baseline entry. A " \
+                       "`# rigor:disable` comment does not reach a row positioned in a `.rbs` file. The real " \
+                       "fix is to regenerate the stale signature or correct the annotation.",
+          severity_authored: :error,
+          severity_by_profile: { lenient: :error, balanced: :error, strict: :error },
+          # Both sides are authored declarations, and a firing needs a proof that no value or call satisfies
+          # both — the ADR-35 both-sides-authored construction, with every doubt routed to the `:info` row.
+          evidence_tier: :high,
+          since: "0.4.0"
+        ),
+
         CheckRules::RULE_SUPPRESSION_UNKNOWN_MARKER => Entry.new(
           id: CheckRules::RULE_SUPPRESSION_UNKNOWN_MARKER,
           summary: "A comment uses a suppression marker Rigor does not recognise " \
@@ -925,6 +1051,7 @@ module Rigor
           since: "0.3.0"
         )
       }.freeze
+      Ractor.make_shareable(ENTRIES)
 
       module_function
 

data/lib/rigor/analysis/run_cache_key.rb

@@ -82,15 +82,23 @@ module Rigor
 
       # @param rbs_config_entries — the RBS-derived config slots
       #   (`rbs.libraries` [+ `rbs.virtual_rbs`]). nil on any failure so a malformed key disables the cache.
-      def descriptor(configuration:, files:, explain:, rbs_config_entries:)
+      # @param template_units_digest — #392 — the run's template-unit identity
+      #   ({Analysis::TemplateUnits#digest}: every unit's source bytes + transform id + synthesis version).
+      #   nil for a project whose plugins declare no `template_globs:`, which is every project today, and a
+      #   nil contributes NO slot — so no existing key moves. A project that DOES have units produces a key
+      #   the ADR-87 boot-slim probe (which loads no plugin and so passes nil) cannot reconstruct: the probe
+      #   simply misses and the full path takes over, the same forgone-fast-lane trade the `rbs.virtual_rbs`
+      #   slot already makes, and never a wrong hit.
+      def descriptor(configuration:, files:, explain:, rbs_config_entries:, template_units_digest: nil)
         Cache::Descriptor.new(
           gems: [Cache::RbsDescriptor.rbs_gem_entry],
-          configs: rbs_config_entries + engine_source_entries + lockfile_entries(configuration) + [
-            config_entry("configuration", Marshal.dump(configuration.to_h)),
-            config_entry("engine",
-                         "#{Rigor::VERSION}:#{Cache::Descriptor::SCHEMA_VERSION}:#{explain}"),
-            config_entry("paths", files.sort.join("\n"))
-          ]
+          configs: rbs_config_entries + engine_source_entries + lockfile_entries(configuration) +
+                   template_unit_entries(template_units_digest) + [
+                     config_entry("configuration", Marshal.dump(configuration.to_h)),
+                     config_entry("engine",
+                                  "#{Rigor::VERSION}:#{Cache::Descriptor::SCHEMA_VERSION}:#{explain}"),
+                     config_entry("paths", files.sort.join("\n"))
+                   ]
         )
       rescue StandardError
         nil
@@ -104,11 +112,12 @@ module Rigor
       #
       # {Cache::EngineSource::Unavailable} is left to propagate into `descriptor`'s rescue, which disables
       # the cache for the run: an engine we cannot identify must not be keyed by its version alone.
-      def engine_source_entries
-        identity = Cache::EngineSource.process_identity
-        return [] if identity.nil?
+      def template_unit_entries(digest)
+        digest.nil? ? [] : [config_entry("template-units", digest)]
+      end
 
-        [config_entry("engine-source", identity)]
+      def engine_source_entries
+        Cache::EngineSource.key_config_entries
       end
 
       # Issue #564 — the two dependency lockfiles, BY CONTENT. Both are inputs to the run's diagnostics and