rigortype 0.3.0 → 0.3.2

data/lib/rigor/language_server/diagnostic_publisher.rb

@@ -3,6 +3,7 @@
 require "tempfile"
 
 require_relative "uri"
+require_relative "publish_batcher"
 require_relative "../analysis/runner"
 require_relative "../analysis/buffer_binding"
 
@@ -14,8 +15,10 @@ module Rigor
     # the Runner, and pushes the resulting LSP `Diagnostic[]` through the writer.
     #
     # Debouncing is wired via an optional `Debouncer` injected at construction (delay defaults to 200ms
-    # quiet-time); without a debouncer each call blocks synchronously (primarily for specs). Ractor-pool
-    # dispatch is queued.
+    # quiet-time); without a debouncer each call blocks synchronously (primarily for specs). When several
+    # buffers' debounce timers elapse around the same moment, the `PublishBatcher` coalesces them into one
+    # `#publish_many` round dispatched across the fork-based worker pool (issue #142) instead of N
+    # independent, GVL-serialized `Runner` calls.
     class DiagnosticPublisher
       # Maps Rigor severity symbols to LSP DiagnosticSeverity
       # integers per spec § "Diagnostic":
@@ -37,6 +40,10 @@ module Rigor
       #   debounced publish fires. 0 with a debouncer means
       #   "schedule on next-tick" (still async); without a
       #   debouncer the value is unused.
+      # The single Debouncer key every save round shares (#246). Per-URI keys would let two saves start two
+      # concurrent rounds; one key means a burst collapses into the last one.
+      PROJECT_ROUND_KEY = :__rigor_project_round__
+
       def initialize(writer:, buffer_table:, project_context:,
                      debouncer: nil, debounce_seconds: 0.2)
         @writer = writer
@@ -44,23 +51,72 @@ module Rigor
         @project_context = project_context
         @debouncer = debouncer
         @debounce_seconds = debounce_seconds
+        @round_lock = Mutex.new
+        @round_running = false
+        @round_pending = false
+        # Issue #142 — coalesces buffers whose OWN debounce timers elapse close together into one
+        # `#publish_many` round instead of N independent GVL-serialized `Runner` calls. Separate from
+        # `@round_lock` above, which single-flights the whole-project SAVE round; this single-flights the
+        # per-buffer DIDCHANGE batch instead. See `PublishBatcher` for the coalescing mechanics.
+        @batcher = PublishBatcher.new(
+          on_batch: ->(uris) { publish_many(uris) },
+          on_error: ->(e) { warn "DiagnosticPublisher batch round: #{e.class}: #{e.message}" }
+        )
       end
 
       # Run analysis for the buffer at `uri` (looked up in the BufferTable) and push a
       # `textDocument/publishDiagnostics` notification. No-op when the URI isn't a `file://` form or the
       # buffer isn't currently open. When a Debouncer is wired, the analysis is scheduled async per the
-      # configured `debounce_seconds`; otherwise it runs inline.
+      # configured `debounce_seconds` and joins the batch coalescing layer (`PublishBatcher`) once its own
+      # quiet-time elapses; otherwise it runs inline (primarily for specs).
       def publish_for(uri)
         path = Uri.to_path(uri)
         return if path.nil?
 
         if @debouncer
-          @debouncer.schedule(uri, delay: @debounce_seconds) { run_and_notify(uri, path) }
+          @debouncer.schedule(uri, delay: @debounce_seconds) { @batcher.enqueue(uri) }
         else
           run_and_notify(uri, path)
         end
       end
 
+      # Issue #142 — publishes N dirty buffers' diagnostics through ONE dispatch across the fork-based
+      # worker pool (`Analysis::Runner::BufferPoolDispatcher`) instead of N independent, GVL-serialized
+      # `Runner` calls. Each URI's OWN `BufferBinding` (its logical path bound to its OWN editor tempfile)
+      # travels with it, so a worker analyses that buffer's in-flight bytes — never the file as it sits on
+      # disk — even when several buffers are dispatched in the same round.
+      #
+      # Degrades to `#run_and_notify`'s existing single-buffer path when only one URI is eligible after
+      # filtering (a buffer closed mid-debounce-window is dropped; a desynchronised one publishes empty
+      # immediately) — a lone edit takes exactly the path it takes today. The dispatcher itself degrades to
+      # sequential in-process execution for any other precondition (see
+      # `BufferPoolDispatcher#dispatchable?`), so a pool that cannot start never fails a publish, only slows
+      # it back down to today's wall time.
+      def publish_many(uris)
+        eligible = uris.uniq.filter_map { |uri| eligible_job(uri) }
+        return if eligible.empty?
+        return run_and_notify(eligible.first.fetch(:uri), eligible.first.fetch(:path)) if eligible.size == 1
+
+        publish_batch(eligible)
+      end
+
+      # Runs one whole-project save round and publishes to the publish set (#246). Called from `didSave`.
+      #
+      # Analysis scope is the whole project; the PUBLISH SET is the open buffers that are not dirty, plus the
+      # buffer that was just saved. A dirty buffer is excluded because only its own `didChange` analysis has
+      # seen its bytes — publishing this round's on-disk answer for it would replace correct markers with
+      # markers for a file the user has already changed.
+      #
+      # Scheduled through the same Debouncer the per-buffer path uses, under one project-wide key, so the
+      # dispatcher never blocks on it.
+      def publish_project(saved_uri)
+        if @debouncer
+          @debouncer.schedule(PROJECT_ROUND_KEY, delay: 0) { run_project_round(saved_uri) }
+        else
+          run_project_round(saved_uri)
+        end
+      end
+
       # Publishes an EMPTY diagnostic array for `uri`. The LSP-spec idiom for "clear inline markers" — called
       # from `didClose` so clients drop stale highlights when the user closes a buffer.
       def publish_empty(uri)
@@ -75,16 +131,141 @@ module Rigor
 
       private
 
+      # Single-flight. The Debouncer only cancels a task that has not started, so without this two rounds
+      # could run concurrently over one session's mutable state. A save that arrives mid-round sets the
+      # pending flag instead of starting a second round, and the running one repeats once when it finishes —
+      # so a burst of saves costs at most one extra round, and the last save is always accounted for.
+      def run_project_round(saved_uri)
+        return unless claim_round
+
+        loop do
+          execute_project_round(saved_uri)
+          break unless consume_pending
+        end
+      end
+
+      # True when this call owns the round. A save arriving while one is in flight records itself as pending
+      # instead — the running round will pick it up.
+      def claim_round
+        @round_lock.synchronize do
+          if @round_running
+            @round_pending = true
+            next false
+          end
+
+          @round_running = true
+          true
+        end
+      end
+
+      # True when a save arrived mid-round and the loop should run once more. Releases ownership otherwise.
+      # `next`, not `break`: inside `Mutex#synchronize`'s block, `break` returns from the SYNCHRONIZE call, so
+      # a `break` written here would leave the caller's `loop` spinning forever — which is exactly what it did
+      # before this was split out.
+      def consume_pending
+        @round_lock.synchronize do
+          next(@round_running = false) unless @round_pending
+
+          @round_pending = false
+          true
+        end
+      end
+
+      # One round: analyse the project as it now stands on disk, then publish each target URI's slice.
+      # The generation captured before the analysis is re-read after it — a `didChangeWatchedFiles` or a
+      # configuration change during a long round invalidates the world these diagnostics describe, and
+      # publishing them would put an answer about a superseded project on the user's screen.
+      def execute_project_round(saved_uri)
+        generation = @project_context.generation
+        diagnostics = @project_context.project_diagnostics
+        return if generation != @project_context.generation
+
+        by_path = diagnostics.group_by(&:path)
+        publish_set(saved_uri).each do |uri|
+          path = Uri.to_path(uri)
+          next if path.nil?
+
+          notify(uri, (by_path[path] || []).filter_map { |diagnostic| to_lsp_diagnostic(diagnostic, path) })
+        end
+      end
+
+      # The URIs this round may speak for: every open buffer whose bytes are the ones on disk. The just-saved
+      # URI qualifies by definition (the client wrote it), and is named explicitly so a client that sends
+      # `didSave` without a preceding applied `didChange` still refreshes it.
+      def publish_set(saved_uri)
+        ([saved_uri] + @buffer_table.uris).uniq.select do |uri|
+          @buffer_table.open?(uri) && !@buffer_table.dirty?(uri) && !@buffer_table.desynchronized?(uri)
+        end
+      end
+
       def run_and_notify(uri, path)
         entry = @buffer_table[uri]
         # The buffer may have been closed during the debounce window — drop the publish; the empty
         # notification from didClose already cleared the markers.
         return if entry.nil?
+        # An incremental change the table could not apply: the held text no longer matches the editor's, so
+        # every span we could compute from it would be misplaced. Clear the markers and stay silent until a
+        # full-text change or a re-open re-establishes the buffer.
+        return notify(uri, []) if @buffer_table.desynchronized?(uri)
 
         diagnostics = run_analysis(path: path, bytes: entry.bytes)
         notify(uri, diagnostics)
       end
 
+      # @return [Hash, nil] `{ uri:, path:, bytes: }` when `uri` is eligible for the batch, or nil to
+      #   exclude it. Mirrors `#run_and_notify`'s own guards: a buffer closed during the debounce window is
+      #   dropped silently (its didClose empty publish already cleared the markers); a desynchronised buffer
+      #   publishes an EMPTY set immediately (same as the single-buffer path) rather than joining the batch.
+      def eligible_job(uri)
+        entry = @buffer_table[uri]
+        return nil if entry.nil?
+
+        path = Uri.to_path(uri)
+        return nil if path.nil?
+
+        if @buffer_table.desynchronized?(uri)
+          notify(uri, [])
+          return nil
+        end
+
+        { uri: uri, path: path, bytes: entry.bytes }
+      end
+
+      # Materialises one tempfile + `BufferBinding` per job, dispatches all of them through
+      # `BufferPoolDispatcher#analyze` in ONE call, and publishes each job's own slice. `dispatcher.analyze`
+      # returns diagnostics IN INPUT ORDER, so `jobs`/`bindings`/the result array stay index-aligned — the
+      # parent absorbs worker results in this stable order, so two runs of the same dirty set publish
+      # byte-identical results.
+      def publish_batch(jobs)
+        with_tempfiles(jobs) do |bound_jobs|
+          bindings = bound_jobs.map { |job| job.fetch(:binding) }
+          dispatcher = Analysis::Runner::BufferPoolDispatcher.new(
+            configuration: @project_context.configuration,
+            cache_store: @project_context.cache_store,
+            environment: @project_context.environment,
+            prebuilt: @project_context.project_scan,
+            workers: worker_count
+          )
+          diagnostics_per_binding = dispatcher.analyze(bindings)
+          bound_jobs.each_with_index do |job, index|
+            diagnostics = diagnostics_per_binding.fetch(index, []).filter_map do |diagnostic|
+              to_lsp_diagnostic(diagnostic, job.fetch(:path))
+            end
+            notify(job.fetch(:uri), diagnostics)
+          end
+        end
+      end
+
+      # Worker-pool size, mirroring `rigor check`'s own precedence minus the CLI flag the LSP does not have:
+      # env `RIGOR_RACTOR_WORKERS` (if set and non-empty) wins, else `.rigor.yml` `parallel.workers:` (0 —
+      # sequential — by default). See `docs/design/20260517-language-server.md` § "Concurrency".
+      def worker_count
+        env_value = ENV.fetch("RIGOR_RACTOR_WORKERS", nil)
+        return [Integer(env_value), 0].max if env_value && !env_value.empty?
+
+        @project_context.configuration.parallel_workers
+      end
+
       # Runs `Analysis::Runner` with a `BufferBinding` so the buffer bytes (instead of the on-disk file) drive
       # the parse. The `Rigor::Analysis::ProjectScan` cached on the ProjectContext is passed through
       # `prebuilt:` so plugin `#prepare`, the dependency-source walker, and the synthetic-method /
@@ -117,6 +298,28 @@ module Rigor
         tmp&.unlink
       end
 
+      # Plural form of `#with_tempfile` for `#publish_batch` — writes one tempfile per job up front, yields
+      # each job Hash augmented with its own `binding:` (a `BufferBinding` pairing the job's logical path
+      # with ITS OWN physical tempfile), and unlinks every tempfile afterward regardless of how the block
+      # exits.
+      def with_tempfiles(jobs)
+        tempfiles = []
+        bound_jobs = jobs.map do |job|
+          tmp = Tempfile.new(["rigor-lsp-buffer-", ".rb"])
+          tmp.write(job.fetch(:bytes))
+          tmp.flush
+          tempfiles << tmp
+          binding = Analysis::BufferBinding.new(logical_path: job.fetch(:path), physical_path: tmp.path)
+          job.merge(binding: binding)
+        end
+        yield bound_jobs
+      ensure
+        tempfiles.each do |tmp|
+          tmp.close
+          tmp.unlink
+        end
+      end
+
       # @return [Hash, nil] the LSP `Diagnostic` Hash, or nil to
       #   skip diagnostics outside the buffer's own path (e.g.
       #   `.rigor.yml`-anchored info diagnostics get filtered —

data/lib/rigor/language_server/incremental_sync.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require "strscan"
+
+module Rigor
+  module LanguageServer
+    # Applies LSP `TextDocumentContentChangeEvent`s to a held buffer under `TextDocumentSyncKind::Incremental`.
+    #
+    # ## Why the offsets need care
+    #
+    # An LSP `Position#character` counts **UTF-16 code units** (`positionEncoding: "utf-16"`, the protocol
+    # default and the only encoding every client supports), while a Ruby String indexes by **codepoint**. The
+    # two agree for every character in the Basic Multilingual Plane — all of ASCII, Latin-1, Greek, Cyrillic,
+    # kana and common kanji — and disagree above U+FFFF, where an emoji or a CJK-extension ideograph is ONE
+    # Ruby character and TWO UTF-16 code units. Reading one as the other shifts every subsequent edit on the
+    # line, and a shifted edit desynchronises the server's text from what the editor shows for the rest of the
+    # session: every diagnostic after that point lands on the wrong span, silently.
+    #
+    # So the conversion is explicit. {.utf16_offset_to_index} walks the line one character at a time, charging
+    # 2 code units for a codepoint above U+FFFF and 1 for everything else, and stops when the requested count
+    # is spent. An all-ASCII line short-circuits the walk, since there the offset IS the index — that is the
+    # keystroke path, and `String#ascii_only?` answers it from the cached coderange.
+    #
+    # ## Failure is a resync, never a guess
+    #
+    # A change whose shape cannot be applied confidently raises {UnappliableChange} rather than producing a
+    # best-effort buffer: {BufferTable#apply_changes} then keeps the last known-good text and marks the URI
+    # desynchronised, which suppresses diagnostics until a full-text change or a re-open re-establishes the
+    # buffer. A stale-but-flagged buffer is recoverable; a silently wrong one is not.
+    module IncrementalSync
+      # Raised when a `contentChanges` entry cannot be applied to the held text: a malformed payload, a
+      # position that is not a non-negative Integer pair, or a range edit against a buffer the server never
+      # received a `didOpen` / full-text change for.
+      class UnappliableChange < StandardError; end
+
+      # LSP considers a line delimited by `\n`, `\r\n`, or a lone `\r`. Ruby's own line splitting only knows
+      # `\n`, so the scan is explicit.
+      LINE_TERMINATOR = /\r\n|\n|\r/
+
+      # UTF-8 encodes exactly the codepoints above the BMP — the ones UTF-16 must encode as a surrogate pair —
+      # in four bytes. So a character's UTF-8 byte length answers "one code unit or two?" without decoding it.
+      SURROGATE_PAIR_BYTES = 4
+
+      module_function
+
+      # Applies every change in order, each against the result of the previous — the LSP contract for a
+      # multi-change `didChange` notification.
+      #
+      # @param text [String, nil] the held buffer text; nil when no buffer is open for the URI.
+      # @param changes [Array<Hash>] the `contentChanges` array.
+      # @return [String] the new buffer text.
+      # @raise [UnappliableChange] if any change cannot be applied.
+      def apply_all(text, changes)
+        raise UnappliableChange, "contentChanges must be an Array, got #{changes.class}" unless changes.is_a?(Array)
+
+        changes.reduce(text) { |acc, change| apply(acc, change) }
+      end
+
+      # Applies one `TextDocumentContentChangeEvent`.
+      #
+      # Two shapes are legal under incremental sync. Without `range` the entry is the full new document text
+      # (clients fall back to it for a paste, an undo, or a file reload, and it stays legal under
+      # `Incremental`); with `range` it replaces the spanned text. `rangeLength` is the deprecated pre-3.16
+      # companion to `range` and is accepted-but-ignored: it is redundant with `range`, historically ambiguous
+      # about its units, and `range` is the authoritative field.
+      #
+      # @raise [UnappliableChange]
+      def apply(text, change)
+        raise UnappliableChange, "contentChanges entry must be a Hash, got #{change.class}" unless change.is_a?(Hash)
+
+        replacement = change[:text]
+        raise UnappliableChange, "contentChanges entry has no `text`" unless replacement.is_a?(String)
+
+        range = change[:range]
+        return replacement.dup if range.nil?
+        raise UnappliableChange, "`range` must be a Hash, got #{range.class}" unless range.is_a?(Hash)
+        raise UnappliableChange, "range edit for a URI with no open buffer" if text.nil?
+
+        splice(text, range, replacement)
+      end
+
+      # Replaces the `range` span of `text` with `replacement`.
+      #
+      # Text that is not valid UTF-8 makes the line scan itself raise. That is not a buffer JSON transport can
+      # deliver, but if one appears there is no offset arithmetic to be confident about, so it becomes a
+      # resync like any other unappliable shape.
+      def splice(text, range, replacement)
+        spans = line_spans(text)
+        from = char_offset(text, spans, range[:start])
+        # A client that inverts the range — or an `end` rounded below `start` off a mid-surrogate
+        # position — would otherwise slice backwards; collapse to an insertion at `from` instead.
+        to = char_offset(text, spans, range[:end]).clamp(from, text.length)
+        "#{text[0, from]}#{replacement}#{text[to..]}"
+      rescue ArgumentError, Encoding::CompatibilityError => e
+        raise UnappliableChange, "held text is not valid UTF-8: #{e.message}"
+      end
+
+      # @return [Array<Array(Integer, Integer)>] one `[content_start, content_end]` pair per line, in Ruby
+      #   character indices. `content_end` excludes the line terminator, so it doubles as the clamp target for
+      #   an over-long `character`. A trailing terminator yields a final empty span — the virtual last line an
+      #   editor puts the cursor on, and the anchor for an end-of-document insert.
+      def line_spans(text)
+        spans = []
+        scanner = StringScanner.new(text)
+        start = 0
+        while scanner.skip_until(LINE_TERMINATOR)
+          stop = scanner.charpos
+          spans << [start, stop - scanner.matched.length]
+          start = stop
+        end
+        spans << [start, text.length]
+        spans
+      end
+
+      # Converts an LSP `Position` into a Ruby character index into `text`.
+      #
+      # A `line` past the last line clamps to the end of the document rather than raising: clients do address
+      # the position one past the final line, and the clamp is what the protocol's own end-of-document
+      # convention implies.
+      def char_offset(text, spans, position)
+        line = position_field(position, :line)
+        character = position_field(position, :character)
+        return text.length if line >= spans.length
+
+        start, stop = spans[line]
+        start + utf16_offset_to_index(text[start...stop], character)
+      end
+
+      # Converts a UTF-16 code-unit offset into `line` to a Ruby character index into the same line.
+      #
+      # Clamps an offset past the end of the line to the line length, per LSP's rule that a `character`
+      # greater than the line length defaults back to the line length.
+      def utf16_offset_to_index(line, units)
+        # Fast path: on an all-ASCII line one UTF-16 code unit is one Ruby character, so the offset is the
+        # index. This is the keystroke case, and `ascii_only?` reads the string's cached coderange.
+        return units.clamp(0, line.length) if line.ascii_only?
+
+        index = 0
+        remaining = units
+        line.each_char do |char|
+          break if remaining <= 0
+
+          remaining -= char.bytesize == SURROGATE_PAIR_BYTES ? 2 : 1
+          index += 1
+        end
+        # `remaining` below zero means the offset addressed the low half of a surrogate pair — a position no
+        # conforming client sends. Round DOWN to the character boundary; splitting the pair is not an option.
+        remaining.negative? ? index - 1 : index
+      end
+
+      def position_field(position, key)
+        value = position.is_a?(Hash) ? position[key] : nil
+        return value if value.is_a?(Integer) && !value.negative?
+
+        raise UnappliableChange, "position `#{key}` must be a non-negative Integer, got #{value.inspect}"
+      end
+    end
+  end
+end

data/lib/rigor/language_server/project_context.rb

@@ -3,6 +3,8 @@
 require_relative "../environment"
 require_relative "../cache/store"
 require_relative "../analysis/runner"
+require_relative "../analysis/incremental_session"
+require_relative "../cache/incremental_snapshot"
 
 module Rigor
   module LanguageServer
@@ -34,6 +36,9 @@ module Rigor
     # watch fires → publish) refreshes automatically; the rare in-flight edit to a substrate-DSL file is the
     # documented edge case.
     class ProjectContext
+      # `generation` is the invalidation counter: a long-running save round (#246) captures it on entry and
+      # discards its result if it moved, so diagnostics computed against a world that has since been
+      # invalidated never reach the editor.
       attr_reader :configuration, :generation
 
       def initialize(configuration:)
@@ -42,6 +47,8 @@ module Rigor
         @environment = nil
         @cache_store = nil
         @project_scan = nil
+        @incremental_session = nil
+        @session_primed = false
       end
 
       # Returns the cached `Rigor::Environment` for this session, building it on first access. The build
@@ -90,6 +97,29 @@ module Rigor
         @project_scan ||= build_project_scan
       end
 
+      # Whole-project diagnostics for one save round (#246). The first call primes an in-process
+      # {Analysis::IncrementalSession} — seeded from the on-disk snapshot a terminal
+      # `rigor check --incremental` may have left, and otherwise from a full baseline; every later call is a
+      # recheck against what changed on disk since.
+      #
+      # The session is never persisted. Its state lives as long as this context, which is what a long-running
+      # server needs, and writing it would race exactly the way the read-only {#cache_store} exists to avoid.
+      # Seeding is therefore one-directional: the terminal warms the server, not the reverse.
+      def project_diagnostics
+        session = (@incremental_session ||= build_incremental_session)
+        return session.recheck.diagnostics if @session_primed
+
+        @session_primed = true
+        diagnostics, = session.run_incremental(
+          snapshot: Cache::IncrementalSnapshot.new(root: @configuration.cache_path),
+          fingerprint: Cache::IncrementalSnapshot.fingerprint(
+            configuration: @configuration, roots: @configuration.paths
+          ),
+          persist: false
+        )
+        diagnostics
+      end
+
       # Drops every cached collaborator and bumps the generation. The next reader rebuilds from scratch.
       # Triggered by `workspace/didChangeWatchedFiles` for project source files and by
       # `workspace/didChangeConfiguration`.
@@ -97,6 +127,10 @@ module Rigor
         @generation += 1
         @environment = nil
         @project_scan = nil
+        # The session's per-file cache was computed against the old environment / project scan, so it cannot
+        # outlive them. The next save round primes a fresh one.
+        @incremental_session = nil
+        @session_primed = false
         # Cache store stays — it's content-addressed; a stale env build won't be served because the file
         # digest mixed into the cache key has changed.
         nil
@@ -104,6 +138,17 @@ module Rigor
 
       private
 
+      # The session shares this context's warm Environment, so a round does not rebuild the RBS universe. It
+      # deliberately does NOT share the prebuilt ProjectScan: a round runs after a save, i.e. after the file
+      # on disk moved, and the scan is what a changed file invalidates.
+      def build_incremental_session
+        Analysis::IncrementalSession.new(
+          configuration: @configuration,
+          environment: environment,
+          cache_store: cache_store
+        )
+      end
+
       def build_project_scan
         runner = Analysis::Runner.new(
           configuration: @configuration,

data/lib/rigor/language_server/publish_batcher.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Rigor
+  module LanguageServer
+    # Issue #142 — coalesces keys that become "ready" close together in wall-clock time into ONE batched
+    # round instead of firing one round per key. `DiagnosticPublisher` uses this to fold a burst of buffers
+    # whose OWN per-URI debounce timers elapse around the same moment (a workspace-wide rename, a git branch
+    # switch that touches many open files) into one `#publish_many` dispatch across the fork-based worker
+    # pool — but the mechanism itself carries no LSP- or URI-specific knowledge, so it stays a small,
+    # independently testable collaborator rather than inline state on `DiagnosticPublisher`.
+    #
+    # Single-flight: the first `#enqueue` call to arrive owns the round and runs `on_batch` with every key
+    # currently pending (deduplicated); a call that arrives while a round is running just adds its key and
+    # returns — the running round loops once more before releasing ownership, so nothing queued mid-round is
+    # dropped. The same claim/consume shape `DiagnosticPublisher#run_project_round` already uses for the
+    # whole-project save round (#246), generalised to an arbitrary key type and an arbitrary batch action.
+    class PublishBatcher
+      # @param on_batch [#call] `(keys) -> void`, called with the deduplicated Array of keys pending at the
+      #   start of one round. May be called more than once in a row when keys keep arriving while a round
+      #   runs.
+      # @param on_error [#call, nil] `(exception) -> void`, called when `on_batch` raises. A round must
+      #   never wedge the coalescing lock for every future `#enqueue` call — ownership is always released
+      #   before this fires. Whatever was mid-flight when the round raised is lost; anything enqueued by a
+      #   concurrent `#enqueue` call after this round's drain but before the rescue stays pending and rides
+      #   the NEXT round instead. Defaults to a no-op (the exception is swallowed silently).
+      def initialize(on_batch:, on_error: nil)
+        @on_batch = on_batch
+        @on_error = on_error
+        @lock = Mutex.new
+        @pending = []
+        @running = false
+      end
+
+      # Adds `key` to the pending set and, if no round is currently running, becomes the round and drains
+      # every key pending (looping until none remain) before returning. A call that arrives while another is
+      # already running the round returns immediately having only enqueued its key.
+      def enqueue(key)
+        start = false
+        @lock.synchronize do
+          @pending << key
+          unless @running
+            @running = true
+            start = true
+          end
+        end
+        return unless start
+
+        run_owned_round
+      end
+
+      private
+
+      def run_owned_round
+        loop do
+          run_batch
+          break unless more_pending?
+        end
+      rescue StandardError => e
+        @lock.synchronize { @running = false }
+        @on_error&.call(e)
+      end
+
+      # True when another key joined `@pending` while this round was running — the caller's loop should run
+      # once more rather than release ownership. Releases ownership (resets `@running`) otherwise.
+      def more_pending?
+        @lock.synchronize do
+          if @pending.empty?
+            @running = false
+            false
+          else
+            true
+          end
+        end
+      end
+
+      def run_batch
+        keys = @lock.synchronize { @pending.uniq.tap { @pending.clear } }
+        @on_batch.call(keys)
+      end
+    end
+  end
+end