rigortype 0.1.5 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b5960ec17b35768103e97d752f8cc6fd78fcb3f12e12fc43dfa41be07ec5317b
-  data.tar.gz: e79c9b25c973c8938e9b2f0a2741cca5195342619827b320ca521ec09e54321e
+  metadata.gz: 0eaff9cf0ef65d44ceb3666a23fb77003a3dbb0361d890e1d2991ef6539499de
+  data.tar.gz: e7fdc58be21409504965f35479559d26bcf4726ba0feabe3fd5128bcffe8419b
 SHA512:
-  metadata.gz: af1e033a25410c0f87943f12d43ab18a3a0d2a79c01307c2117c2fc15be4c9db3cb28e6fec10ce598ef6a5bfa063227f280c023a0f7e9025b06c69946df4654d
-  data.tar.gz: 351b3275dd35f37a11d30a696627e23a6cdca31bfb94fa3eacae762d2de624e4a914c6f8f4eebdd7df0bd17fd9fac13fe55ac434957509b742771a00d352a981
+  metadata.gz: 94aae7605ca3243e7226e6f2e1c844f141d3ef04995751718e08ef5fb9dfa550455c6c87420e731332b765ee262442ed2608b5f0d7b05a25b982615b993114e5
+  data.tar.gz: f2dedba8fb33b9f7d98ddaa4debcec042edf56396c22a791ce8897736839c559240cb20158916f7c2bc5f483da06c1bebb7212ec2f24b16c3554164f849da621

data/README.md

@@ -15,13 +15,32 @@ for any class it can find, and reports a small but trustworthy
 catalogue of bugs (undefined methods on typed receivers, wrong
 positional arity, provable `Integer / 0`, …).
 
-The differentiator is a richer type vocabulary than ordinary
-RBS expresses. Rigor reasons about *what values an expression
-actually produces* — literal values, integer ranges,
-refinement-type carriers, per-position tuple / hash shapes —
-not just *which class an object belongs to*. See **[Beyond
-`Integer` and `String`](#beyond-integer-and-string-rigors-richer-type-vocabulary)**
-for the full type-model story; the short pitch is below.
+**Two design commitments drive Rigor.**
+
+1. **Types are facts, not wishes.** Hand-written type
+   annotations drift from the implementation the moment they
+   are written. Rigor infers from the code itself — every
+   carrier in its type vocabulary is derived from what your
+   source actually produces, not from a signature you authored
+   and might forget to update. When you do want RBS in
+   `sig/`, [`rigor sig-gen`](docs/adr/14-rbs-sig-generation.md)
+   emits it from inference results so the written form starts
+   in sync with reality, and `tighter-return` candidates flag
+   the cases where an existing `.rbs` is already weaker than
+   what the implementation provably returns.
+2. **Programmable inference beyond unions.** A plain union
+   (`Integer | nil`) is not the type story Ruby needs. Rigor
+   reasons about *what values an expression actually
+   produces* — literal values, integer ranges, refinement
+   carriers, per-position tuple / hash shapes, bound-method
+   bindings — and exposes a plugin extension API plus an
+   [ADR-16](docs/adr/16-macro-expansion.md) macro / DSL
+   expansion substrate so Rails-shape DSLs are first-class
+   type sources rather than analysis blind spots.
+
+See **[Beyond `Integer` and `String`](#beyond-integer-and-string-rigors-richer-type-vocabulary)**
+for the full type-model story; the carrier-zoo table is the
+short pitch.
 
 When you want tighter types than RBS expresses, refine them
 through the
@@ -426,19 +445,20 @@ plugin-supplied type-vocabulary resolvers, and
 [ADR-16](docs/adr/16-macro-expansion.md) macro / DSL expansion
 substrate (declarative Tier A block-as-method / Tier B
 trait-inlining-registry / Tier C heredoc-template / Tier D
-external-file inclusion). **Twenty-four worked examples** ship
-under [`examples/`](examples/) — each is a fully-shaped plugin
-gem with a runnable demo and an end-to-end integration spec.
+external-file inclusion). Production plugins ship under
+[`plugins/`](plugins/) — each is a fully-shaped plugin gem
+with a runnable demo and an end-to-end integration spec.
+Plugin-contract walkthroughs (deliberately simplified
+virtual use cases that spotlight one architectural surface
+per example) live under [`examples/`](examples/).
 
-**Plugin-contract teaching examples** (focus on a single
-extension-point):
+**Plugin-contract walkthroughs** (`examples/`, focus on a
+single extension-point):
 
 - [`rigor-deprecations`](examples/rigor-deprecations/) —
   smallest possible plugin (~80 lines); config-driven rules.
 - [`rigor-lisp-eval`](examples/rigor-lisp-eval/) — typing literal
   AST arguments at a method call.
-- [`rigor-statesman`](examples/rigor-statesman/) — two-pass DSL
-  analysis (collect declarations, then validate references).
 - [`rigor-pattern`](examples/rigor-pattern/) — plugin →
   analyzer collaboration via `Scope#type_of` and the
   literal-string carrier.
@@ -446,7 +466,13 @@ extension-point):
   tracking through arithmetic.
 - [`rigor-routes`](examples/rigor-routes/) — `Plugin::IoBoundary`
   reads under `TrustPolicy` plus cache producers.
-- [`rigor-typescript-utility-types`](examples/rigor-typescript-utility-types/)
+
+**Other production plugins for type-language extension** (`plugins/`):
+
+- [`rigor-statesman`](plugins/rigor-statesman/) — two-pass DSL
+  analysis (collect declarations, then validate references)
+  for the Statesman state-machine gem.
+- [`rigor-typescript-utility-types`](plugins/rigor-typescript-utility-types/)
   — `Plugin::TypeNodeResolver` chain wiring TS-canonical names
   (`Pick` / `Omit` / `Partial` / `Required` / `Readonly`) onto
   Rigor's shape-projection type functions.
@@ -454,16 +480,16 @@ extension-point):
 **Macro expansion substrate consumers** (ADR-16 — declarative
 manifest entries, no walker code):
 
-- [`rigor-sinatra`](examples/rigor-sinatra/) — **Tier A**
+- [`rigor-sinatra`](plugins/rigor-sinatra/) — **Tier A**
   block-as-method. Recognises Sinatra's nine class-level HTTP
   verb methods and narrows the route block's `self_type` so
   bare `params` / `redirect` / `halt` resolve through
   `Sinatra::Base`'s RBS.
-- [`rigor-dry-struct`](examples/rigor-dry-struct/) — **Tier C**
+- [`rigor-dry-struct`](plugins/rigor-dry-struct/) — **Tier C**
   heredoc-template. Synthesises a reader on every `Dry::Struct`
   subclass for each `attribute :name, T` / `attribute? :name, T`
   call.
-- [`rigor-devise`](examples/rigor-devise/) — **Tier B**
+- [`rigor-devise`](plugins/rigor-devise/) — **Tier B**
   trait-inlining registry mirroring `lib/devise/modules.rb`.
   Each `devise :strategy_a, :strategy_b` call explodes the
   included module's RBS instance methods onto the calling model
@@ -472,28 +498,30 @@ manifest entries, no walker code):
 
 **Rails ecosystem plugins** (Tier 1 + Tier 2 + Tier 3 + Sorbet):
 
-- Tier 1: [`rigor-rails-routes`](examples/rigor-rails-routes/),
-  [`rigor-rails-i18n`](examples/rigor-rails-i18n/),
-  [`rigor-actionmailer`](examples/rigor-actionmailer/),
-  [`rigor-activejob`](examples/rigor-activejob/).
-- Tier 2: [`rigor-actionpack`](examples/rigor-actionpack/)
+- Tier 1: [`rigor-rails-routes`](plugins/rigor-rails-routes/),
+  [`rigor-rails-i18n`](plugins/rigor-rails-i18n/),
+  [`rigor-actionmailer`](plugins/rigor-actionmailer/),
+  [`rigor-activejob`](plugins/rigor-activejob/).
+- Tier 2: [`rigor-actionpack`](plugins/rigor-actionpack/)
   (4 phases — routes / filters / renders / strong-params),
-  [`rigor-factorybot`](examples/rigor-factorybot/),
-  [`rigor-activerecord`](examples/rigor-activerecord/) —
+  [`rigor-factorybot`](plugins/rigor-factorybot/),
+  [`rigor-activerecord`](plugins/rigor-activerecord/) —
   publishes `:model_index` via ADR-9 for the other two
   to consume.
-- Tier 3: [`rigor-pundit`](examples/rigor-pundit/),
-  [`rigor-sidekiq`](examples/rigor-sidekiq/),
-  [`rigor-rspec`](examples/rigor-rspec/),
-  [`rigor-actioncable`](examples/rigor-actioncable/).
-- Parallel: [`rigor-sorbet`](examples/rigor-sorbet/) — ingests
+- Tier 3: [`rigor-pundit`](plugins/rigor-pundit/),
+  [`rigor-sidekiq`](plugins/rigor-sidekiq/),
+  [`rigor-rspec`](plugins/rigor-rspec/),
+  [`rigor-actioncable`](plugins/rigor-actioncable/).
+- Parallel: [`rigor-sorbet`](plugins/rigor-sorbet/) — ingests
   Sorbet `sig` / `T.let` / `T.cast` / `T.must` / `T.bind` /
   `T.assert_type!` / `T.reveal_type` / `T.absurd` and RBI
   files as type sources.
 
-[`examples/README.md`](examples/README.md) is the plugin
-authoring landing page — comparison table, recommended reading
-order, and the architectural map of which surface each example
+[`plugins/README.md`](plugins/README.md) is the production
+plugin catalogue (Rails / RSpec / dry-rb / Sorbet / etc.) and
+[`examples/README.md`](examples/README.md) is the walkthrough
+catalogue — comparison table, recommended reading order, and
+the architectural map of which surface each walkthrough
 exercises. The binding contract for the plugin API lives in
 [`docs/adr/2-extension-api.md`](docs/adr/2-extension-api.md);
 the slice-by-slice normative specs are under
@@ -532,7 +560,7 @@ Common knobs the file exposes:
 
 ## Status
 
-Current released version: **`v0.1.4`**. The analyzer is usable
+Current released version: **`v0.1.5`**. The analyzer is usable
 on real Ruby code today; the rule catalogue is deliberately
 narrow — Rigor's stance is to surface zero false positives
 while the inference surface stabilises. Forward-looking commitments
@@ -540,50 +568,21 @@ while the inference surface stabilises. Forward-looking commitments
 [`docs/ROADMAP.md`](docs/ROADMAP.md); the release-by-release
 "what shipped" record is [`CHANGELOG.md`](CHANGELOG.md).
 
-`v0.1.4` (released 2026-05-14) delivered:
-
-- **[ADR-10](docs/adr/10-dependency-source-inference.md) closed
-  end-to-end** — opt-in gem-source inference, per-gem budget,
-  cache slice, and the `dynamic.dependency-source.boundary-cross`
-  `:info` diagnostic that surfaces RBS / gem-source overlap
-  under `mode: :full`.
-- **[ADR-11](docs/adr/11-sorbet-input-adapter.md) primary surface
-  + per-call-site assertion gating** — `rigor-sorbet` ingests
-  Sorbet `sig { ... }` blocks, `T.let` / `T.cast` / `T.must` /
-  `T.bind` / `T.assert_type!` / `T.reveal_type` / `T.absurd`,
-  and RBI files. Per-call-site `enforce_sigil` gates assertion
-  recognisers by the caller file's `# typed:` sigil.
-- **[ADR-13](docs/adr/13-typenode-resolver-plugin.md) plugin
-  TypeNode resolver + TypeScript-utility-type adapter** —
-  `Plugin::TypeNodeResolver` extension point + five
-  Rigor-canonical shape-projection type functions
-  (`pick_of` / `omit_of` / `partial_of` / `required_of` /
-  `readonly_of`) + the opt-in `rigor-typescript-utility-types`
-  plugin mapping TS spellings onto the core functions.
-  `Pick[T, :a | :b]` round-trips through the directive grammar.
-- **[ADR-14](docs/adr/14-rbs-sig-generation.md) — `rigor sig-gen`
-  CLI** — emits RBS from inference results across five
-  classifications (`new-file` / `new-method` / `tighter-return`
-  / `equivalent` / `skipped`); `--params=untyped` default,
-  `--params=observed` opt-in via `--observe=PATH`.
-- **`Method` carrier (`Type::BoundMethod`)** —
-  `Object#method(:sym).call` / `.()` / `[]` round-trip with
-  full precision instead of collapsing to `untyped`.
-- **Rails ecosystem (Tier 1 + Tier 2)** — `rigor-rails-routes`,
-  `rigor-rails-i18n`, `rigor-actionmailer`, `rigor-activejob`,
-  `rigor-actionpack` (4 phases), `rigor-factorybot`, and
-  `rigor-activerecord` publishing `:model_index` via the
-  ADR-9 cross-plugin fact channel.
-
-Twenty-four worked plugin examples now ship under
+`v0.1.5` (released 2026-05-16) delivered (full slice list in `CHANGELOG.md` § `[0.1.5]`):
+
+- **ADR-15 Ractor migration end-to-end** (Phases 1–4c + 4b.x) — opt-in `rigor check --workers=N` parallelism; pool ≡ sequential proven on 14 real-world projects (31,840 files); spec-suite wall-clock 162s → 27s on 12 cores via `parallel_tests`.
+- **[ADR-16](docs/adr/16-macro-expansion.md) macro / DSL expansion substrate** — four-tier declarative manifest contract (block-as-method, trait-inlining registry, heredoc-template, external-file) with Tier B/C precision promotion and three worked consumer plugins (`rigor-sinatra`, `rigor-devise`, `rigor-dry-struct`). Closes ROADMAP O2 at the WD13 floor.
+- **Real-world Rails / Ruby survey** — fourteen projects swept; opt-in `rigor-activesupport-core-ext` RBS bundle delivers `−75 %` total diagnostics; built-in vendored gem RBS for six native-extension gems (`pg` / `mysql2` / `nokogiri` / `bcrypt` / `redis` / `idn-ruby`); Bundler-aware sig discovery; `RbsLoader#env` failure-memo (~550× speedup on a conflicting sig).
+- **O4 Layer 3 target-project RBS source discovery (slices 1+2+3)** — `Gemfile.lock` parse + bundle-sig filter, `rbs_collection.lock.yaml` awareness, missing-gem `:info` diagnostic.
+- **DEFAULT_LIBRARIES stdlib coverage expansion** — out-of-the-box RBS classes available 1,273 → 1,427 (+154); 31 additional stdlib libraries auto-load.
+- **`is_a?(C)` lexical-nesting constant resolution** — predicate-narrowing now mirrors Ruby's `Module.nesting`-driven lookup.
+
+Production plugins ship under [`plugins/`](plugins/) (Rails /
+RSpec / dry-rb / Sorbet / etc.) — see
+[`plugins/README.md`](plugins/README.md) for the catalogue.
+Plugin-contract walkthroughs ship under
 [`examples/`](examples/) — see
-[`examples/README.md`](examples/README.md) for the comparison
-table. The current `[Unreleased]` cycle on `master` (release
-pending) also delivered the [ADR-16](docs/adr/16-macro-expansion.md)
-macro / DSL expansion substrate (four-tier declarative
-manifest contract + engine integration + Tier B/C precision
-promotion); see `CHANGELOG.md` `[Unreleased]` for the full
-landing notes.
+[`examples/README.md`](examples/README.md).
 
 ## Contributing
 
@@ -594,5 +593,3 @@ skill documentation contributors should know about.
 ## License
 
 Mozilla Public License Version 2.0. See [`LICENSE`](LICENSE).
-</content>
-</invoke>

data/lib/rigor/analysis/baseline.rb

@@ -0,0 +1,347 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Rigor
+  module Analysis
+    # ADR-22 Slice 1 — PHPStan-shaped per-project baseline.
+    #
+    # Loads `.rigor-baseline.yml`, filters a current run's
+    # diagnostic stream against the recorded buckets, and emits
+    # an `(surfaced, silenced_count)` pair for the CLI to render.
+    #
+    # Two row shapes are accepted (WD1):
+    #
+    #   # rule-ID row — bucket key (path, qualified_rule)
+    #   - file: app/models/user.rb
+    #     rule: call.undefined-method
+    #     count: 3
+    #
+    #   # message-pattern row — bucket key
+    #   #   (path, qualified_rule, message_regex)
+    #   - file: app/lib/sig.rb
+    #     rule: call.undefined-method
+    #     message: "undefined method `merge' for Array"
+    #     count: 1
+    #
+    # ## Semantics per (file, rule [, message]) bucket (WD4)
+    #
+    #   actual <= count    → ALL diagnostics in the bucket are silenced.
+    #   actual >  count    → ALL diagnostics in the bucket surface
+    #                        (not just the excess delta — the bucket
+    #                        has crossed its threshold; the team's
+    #                        review focus shifts from "which N is new"
+    #                        to "what's going on with this rule in
+    #                        this file as a whole").
+    #
+    # ## Filter pipeline position (WD6)
+    #
+    # The baseline filter runs LAST among the diagnostic-suppression
+    # layers:
+    #
+    #   emit →  `# rigor:disable` (per-line)
+    #        →  `# rigor:disable-file`
+    #        →  severity_profile re-stamp
+    #        →  baseline filter (this class)
+    #        →  output
+    #
+    # ## Loading (WD2 (b))
+    #
+    # `Baseline.load` is called by the CLI when it has resolved
+    # an explicit baseline path (from `--baseline=PATH` on the
+    # CLI or `baseline: <path>` in `.rigor.yml`). The presence
+    # of `.rigor-baseline.yml` on disk alone never triggers a
+    # load — that's the CLI / Configuration's job to enforce.
+    class Baseline
+      # The bucket key is intentionally tuple-shaped so rule-ID
+      # rows and message-pattern rows can coexist in a single
+      # multimap. `message` is `nil` for rule-ID rows; a Regexp
+      # for message-pattern rows.
+      # `count` shadows Struct#count; intentional — `count` is the
+      # PHPStan-compatible field name and we don't use the
+      # Enumerable-style `Struct#count` on Bucket instances.
+      Bucket = Struct.new(:file, :rule, :message_regex, :count, keyword_init: true) # rubocop:disable Lint/StructNewOverride
+
+      CURRENT_VERSION = 1
+
+      class << self
+        # Load a baseline file from disk. Returns `nil` when the
+        # path is nil (the caller's "no baseline configured"
+        # state). Raises {LoadError} on malformed content;
+        # callers translate to a user-facing diagnostic.
+        def load(path)
+          return nil if path.nil?
+          return new([]) unless File.exist?(path)
+
+          raw = YAML.safe_load_file(path, permitted_classes: [Symbol])
+          parse_loaded(raw, path: path)
+        end
+
+        # Build a baseline from a current run's diagnostic stream.
+        # `match_mode:` is `:rule` (default) or `:message`. The
+        # message-mode generator passes literal messages through
+        # `Regexp.escape` so generated rows never accidentally
+        # over-match on punctuation.
+        def from_diagnostics(diagnostics, match_mode: :rule)
+          raise ArgumentError, "match_mode must be :rule or :message" unless %i[rule message].include?(match_mode)
+
+          grouped = group_for_baseline(diagnostics, match_mode)
+          buckets = grouped.map do |key, entries|
+            Bucket.new(
+              file: key[0],
+              rule: key[1],
+              message_regex: key[2],
+              count: entries.size
+            )
+          end
+          new(buckets)
+        end
+
+        private
+
+        def parse_loaded(raw, path:)
+          raise LoadError, "#{path}: expected a Hash at top level, got #{raw.class}" unless raw.is_a?(Hash)
+
+          version = raw["version"]
+          unless version == CURRENT_VERSION
+            raise LoadError, "#{path}: unsupported `version: #{version.inspect}` (expected #{CURRENT_VERSION})"
+          end
+
+          rows = raw["ignored"] || []
+          raise LoadError, "#{path}: `ignored:` must be an Array" unless rows.is_a?(Array)
+
+          new(rows.each_with_index.map { |row, idx| parse_row(row, path: path, index: idx) })
+        end
+
+        def parse_row(row, path:, index:)
+          raise LoadError, "#{path}: ignored[#{index}] must be a Hash" unless row.is_a?(Hash)
+
+          file = row["file"] or raise LoadError, "#{path}: ignored[#{index}] missing `file:`"
+          rule = row["rule"] or raise LoadError, "#{path}: ignored[#{index}] missing `rule:`"
+          count = row["count"]
+          unless count.is_a?(Integer) && count.positive?
+            raise LoadError, "#{path}: ignored[#{index}] `count:` must be a positive Integer (got #{count.inspect})"
+          end
+
+          message_regex = nil
+          if (message = row["message"])
+            message_regex = compile_message_regex(message, path: path, index: index)
+          end
+
+          Bucket.new(file: file, rule: rule, message_regex: message_regex, count: count)
+        end
+
+        def compile_message_regex(source, path:, index:)
+          Regexp.new(source.to_s)
+        rescue RegexpError => e
+          raise LoadError, "#{path}: ignored[#{index}] `message:` is not a valid Regexp: #{e.message}"
+        end
+
+        # Returns Hash{[file, rule, regex_or_nil] => Array<Diagnostic>}.
+        # In message mode, each unique message gets its own bucket;
+        # in rule mode, every diagnostic for a (file, rule) pair
+        # contributes to a single bucket regardless of message.
+        def group_for_baseline(diagnostics, match_mode)
+          diagnostics.each_with_object({}) do |diag, into|
+            next if diag.qualified_rule.nil?
+            next if diag.path.nil?
+
+            key = case match_mode
+                  when :rule
+                    [diag.path, diag.qualified_rule, nil]
+                  when :message
+                    [diag.path, diag.qualified_rule, message_pattern_for(diag.message)]
+                  end
+            (into[key] ||= []) << diag
+          end
+        end
+
+        # Generates a Regexp source string for the baseline row.
+        # The string is `Regexp.escape`d so the YAML round-trip
+        # produces a regex that matches the literal message.
+        # Users hand-editing the row can replace the escaped
+        # form with a pattern.
+        def message_pattern_for(message)
+          Regexp.new(Regexp.escape(message.to_s))
+        end
+      end
+
+      class LoadError < StandardError; end
+
+      attr_reader :buckets
+
+      def initialize(buckets)
+        @buckets = buckets.freeze
+        # For each (file, qualified_rule) pair, two arrays:
+        # - rule-ID rows (message_regex == nil)
+        # - message-pattern rows (message_regex != nil)
+        # The matcher walks message-pattern rows first (tighter
+        # match takes precedence); diagnostics that don't match
+        # any message row fall through to the rule-ID row if
+        # one exists.
+        @by_pair = buckets.group_by { |b| [b.file, b.rule] }.freeze
+        freeze
+      end
+
+      # Apply the baseline filter to a diagnostic stream.
+      #
+      # Returns a 2-tuple:
+      # - `surfaced` — the diagnostics that survived the filter
+      #   (new findings + entire over-threshold buckets).
+      # - `silenced_count` — how many diagnostics the baseline
+      #   suppressed (for the WD7 stderr summary line).
+      def filter(diagnostics)
+        return [diagnostics, 0] if buckets.empty?
+
+        grouped = group_diagnostics_for_filtering(diagnostics)
+        surfaced = []
+        silenced_count = 0
+
+        grouped.each_value do |entries|
+          bucket = entries[:bucket]
+          diags = entries[:diagnostics]
+          # No matching bucket → all surface as new findings.
+          # `actual <= count` → all silenced (within threshold,
+          # WD4). `actual >  count` → all surface (over
+          # threshold, WD4).
+          if bucket && diags.size <= bucket.count
+            silenced_count += diags.size
+          else
+            surfaced.concat(diags)
+          end
+        end
+
+        # Diagnostics that lacked a rule or a path bypass the
+        # baseline entirely (the baseline can't address them).
+        unkeyable = diagnostics.reject { |d| d.qualified_rule && d.path }
+        [surfaced + unkeyable, silenced_count]
+      end
+
+      # A single bucket's drift state for slice 2 inspection.
+      # `status` is one of:
+      #
+      # - `:within`    — `actual <= count` (silenced by the filter).
+      # - `:over`      — `actual > count` (over threshold; surfaced
+      #                  in the regular `rigor check` output).
+      # - `:cleared`   — `actual == 0` (the bucket can be pruned).
+      # - `:reducible` — `0 < actual < count` (the bucket's count
+      #                  can be tightened; future `regenerate`
+      #                  slice 5 handles this).
+      DriftRow = Struct.new(:bucket, :actual_count, :status, keyword_init: true) do
+        def delta
+          actual_count - bucket.count
+        end
+      end
+
+      # Walk the current diagnostic stream and report
+      # bucket-level drift. Each baseline bucket becomes one
+      # DriftRow regardless of whether the current run still
+      # matches it.
+      #
+      # @param diagnostics [Array<Diagnostic>] current run's
+      #   diagnostic stream (PRE-filter — pass the raw
+      #   `result.diagnostics` from `Runner#run`, not the
+      #   post-baseline surface).
+      # @return [Array<DriftRow>] one entry per baseline bucket,
+      #   in baseline-file order.
+      def audit(diagnostics)
+        counts = Hash.new(0)
+        diagnostics.each do |diag|
+          next if diag.qualified_rule.nil? || diag.path.nil?
+
+          bucket = claim_bucket_for(diag)
+          counts[bucket_key(bucket)] += 1 if bucket
+        end
+
+        buckets.map do |bucket|
+          actual = counts[bucket_key(bucket)]
+          DriftRow.new(bucket: bucket, actual_count: actual, status: status_for(actual, bucket.count))
+        end
+      end
+
+      # Returns a new Baseline with the given buckets dropped.
+      # Used by `rigor baseline prune` (slice 2) to remove
+      # cleared buckets (`actual == 0`) from the on-disk file.
+      def without(buckets_to_drop)
+        dropset = buckets_to_drop.to_set
+        self.class.new(buckets.reject { |b| dropset.include?(b) })
+      end
+
+      # Serialise to a YAML string. The generator path writes
+      # this through `File.write`; the dump format is stable
+      # across versions of this class as long as the bucket
+      # shape is unchanged.
+      def to_yaml
+        rows = buckets.map do |bucket|
+          row = { "file" => bucket.file, "rule" => bucket.rule }
+          row["message"] = bucket.message_regex.source if bucket.message_regex
+          row["count"] = bucket.count
+          row
+        end
+
+        document = { "version" => CURRENT_VERSION, "ignored" => rows }
+        YAML.dump(document)
+      end
+
+      # The number of buckets recorded. Useful for the CLI
+      # summary on `generate`.
+      def size
+        buckets.size
+      end
+
+      def empty?
+        buckets.empty?
+      end
+
+      private
+
+      def status_for(actual, count)
+        return :cleared if actual.zero?
+        return :over if actual > count
+        return :within if actual == count
+
+        :reducible
+      end
+
+      def bucket_key(bucket)
+        [bucket.file, bucket.rule, bucket.message_regex&.source]
+      end
+
+      def group_diagnostics_for_filtering(diagnostics)
+        # First pass: bin each diagnostic into the bucket that
+        # claims it. Message-pattern rows take precedence over
+        # rule-ID rows because they're more specific. A
+        # diagnostic that matches no row goes into a synthetic
+        # "no-bucket" bin keyed by (file, rule).
+        bins = {}
+        diagnostics.each do |diag|
+          next if diag.qualified_rule.nil? || diag.path.nil?
+
+          bucket = claim_bucket_for(diag)
+          key = if bucket
+                  [bucket.file, bucket.rule,
+                   bucket.message_regex&.source]
+                else
+                  [diag.path, diag.qualified_rule, :__none__]
+                end
+          bin = (bins[key] ||= { bucket: bucket, diagnostics: [] })
+          bin[:diagnostics] << diag
+        end
+        bins
+      end
+
+      def claim_bucket_for(diagnostic)
+        candidates = @by_pair[[diagnostic.path, diagnostic.qualified_rule]]
+        return nil if candidates.nil? || candidates.empty?
+
+        # Tighter (message-pattern) buckets first, then the
+        # rule-ID bucket as fallback.
+        message_buckets, rule_buckets = candidates.partition(&:message_regex)
+        message_buckets.each do |b|
+          return b if b.message_regex.match?(diagnostic.message.to_s)
+        end
+        rule_buckets.first
+      end
+    end
+  end
+end

data/lib/rigor/analysis/buffer_binding.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Analysis
+    # Binds one logical project path (the path the user is editing,
+    # e.g. `lib/foo.rb`) to a physical file containing the in-flight
+    # buffer bytes (e.g. `/tmp/9539itfeh2.rb`). When the runner /
+    # workers / pre-passes need to read source for the logical path,
+    # they read from the physical path instead; when they emit a
+    # `Diagnostic`, the path is the logical one so editors highlight
+    # the buffer the user is actually looking at.
+    #
+    # See `docs/design/20260516-editor-mode.md` for the design.
+    # The CLI surfaces this through paired `--tmp-file` /
+    # `--instead-of` flags on `rigor check` and `rigor type-of`;
+    # programmatic callers pass a `BufferBinding` to `Runner.new`.
+    BufferBinding = Data.define(:logical_path, :physical_path) do
+      # Returns the physical path to read bytes from when the caller
+      # is about to parse `path`. For non-logical paths returns the
+      # input unchanged. Cheap to call on every path; the binding is
+      # singular today (one buffer per run).
+      def resolve(path)
+        path == logical_path ? physical_path : path
+      end
+
+      # Returns the path the caller should report in user-facing
+      # output (diagnostics, run stats) when it currently holds the
+      # physical path. The inverse of `#resolve`. Non-physical paths
+      # pass through unchanged, so it is safe to stamp every
+      # outgoing path through this helper.
+      def display_path(path)
+        path == physical_path ? logical_path : path
+      end
+    end
+  end
+end