rigortype 0.3.9 → 0.4.0

data/docs/manual/plugins/rigor-rbs-inline.md

@@ -45,40 +45,97 @@ plugin id/version + config), so an unchanged second run skips the parse.
 | Rule | Severity | Fires when |
 | --- | --- | --- |
 | `plugin.rbs-inline.source-rbs-synthesis-failed` | info | rbs-inline could not parse a file; analysis falls back to no inline-RBS contribution and the diagnostic carries the upstream error |
-| `plugin.rbs-inline.source-rbs-annotation-not-honoured` | info | an annotation parsed successfully but contributed nothing — the file's other annotations still apply. Two causes: a member your `sig/` also declares (see [Precedence](#precedence)), and the `# @rbs module-self: Foo` spelling (see below) |
+| `plugin.rbs-inline.source-rbs-annotation-not-honoured` | info | an annotation parsed successfully but contributed nothing — the file's other annotations still apply. Six causes: a member your `sig/` also declares where Rigor cannot tell which of the two is more precise (see [Precedence](#precedence)), the `# @rbs module-self: Foo` spelling (see below), a `#:` line whose type does not parse (see [Unparseable `#:` types](#unparseable--types)), a same-line `# @rbs %a{…}` whose method type does not parse (see [Same-line annotations](#same-line-annotations)), a `# @rbs name: T` parameter type that does not parse (see [Unparseable `# @rbs name:` types](#unparseable--rbs-name-types)), and an `@rbs`-prefixed tag the gem does not recognise (see [An unrecognised tag after `@rbs`](#an-unrecognised-tag-after-rbs)) |
+| `rbs.contradicting-signature` | error | an inline declaration contradicts the `sig/` declaration of the same method, or an inline `%a{rigor:v1:…}` refinement is outside its own declared type (see [Precedence](#precedence)). A core rule rather than the plugin's own, so it carries no `plugin.rbs-inline.` prefix |
 
 ## Precedence
 
 When a method is declared **both** in `sig/` and by an inline
-annotation, **the `.rbs` wins, per member.** The inline signature for
-that one method is dropped; every other annotation in the file still
-binds, and the class keeps its method surface.
+annotation, Rigor **compares the two**, position by position — each
+parameter, the return type, a block's parameters and return — and
+exactly one of them binds. Every other annotation in the file still
+binds either way, and the class keeps its method surface.
 
 ```ruby
-# lib/demo.rb                  # sig/demo.rbs
-class Demo                     # class Demo
-  # @rbs (Integer) -> String   #   def shared: (String) -> Integer  ← this one wins
-  def shared(v) = v.to_s       #   def only_sig: () -> String
-                               # end
-  # @rbs (Integer) -> Integer
-  def only_inline(v) = v + 1   # ← inline-only: still binds
+# lib/demo.rb                          # sig/demo.rbs
+class Demo                             # class Demo
+  # @rbs dir: :asc | :desc             #   def order: (Symbol dir) -> void
+  def order(dir) = nil                 #   def shared: (String) -> Integer
+                                       # end
+  # @rbs (Integer) -> String
+  def shared(v) = v.to_s
 end
 ```
 
-Each dropped member is reported once as
-`plugin.rbs-inline.source-rbs-annotation-not-honoured`, naming the
-member and the `.rbs` that won. Delete one of the two declarations to
-make the inline annotation take effect.
-
-`sig/` wins because it is the reviewed artefact — the one you diff in
-review and the one `rigor sig-gen --diff` reasons about. There is no
-upstream rule to defer to: rbs merges an inline `.rb` declaration and a
-`.rbs` one into a single class entry and ranks neither, so Steep reports
-the same overlap as a signature error and the class still fails to
-build. Rigor keeps the reporting and drops the degradation
-([ADR-32](../../adr/32-rbs-inline-comment-ingestion.md) WD13) — left to
-collide, one duplicated method costs the class every other method, and
-each call on it, real methods and typos alike, reads `Dynamic[top]`.
+- **One refines the other: the more precise one binds, silently.**
+  `:asc | :desc` is a subtype of `Symbol`, so `Demo#order` takes the
+  inline contract and `order(:up)` is an argument-type error, where
+  the `.rbs` alone let it pass. The merge takes the narrower type in
+  every position, parameters included, on purpose: both declarations
+  are yours, and the narrower one is what you stated. `String` in
+  `sig/` beside `non-empty-string` inline reads as `non-empty-string`.
+  `untyped`, `void` and `top` are consistent with anything and say the
+  least, so `sig/`'s `-> untyped` beside an inline `-> void` is quiet.
+  Identical declarations — what `rigor sig-gen` writes for an annotated
+  method — are quiet too. The inline side binds only if the `.rbs`
+  member loses nothing by it: the same visibility, and every
+  annotation it carries (a predicate, an assertion, an effect
+  envelope) also on the inline one.
+- **They contradict: an error, and the `.rbs` binds.** If `Demo#shared`
+  took a `::String` in `sig/` and an `::Integer` inline, no value would
+  be both, so the run would report
+  [`rbs.contradicting-signature`](../04-diagnostics.md#rule-rbs-contradicting-signature)
+  at the `sig/` line, naming the annotated file. Spelled `String` and
+  `Integer`, as in the example, the pair is undecided instead (below). Positional counts that
+  cannot meet, or a keyword one side requires and the other cannot take
+  in any form, contradict the same way. The error needs a proof, and
+  only Ruby core or stdlib classes written absolutely (`::String`,
+  `::Integer`) give one, read from their RBS hierarchy. A module such
+  as `Comparable` never counts, since any class may include it; nor
+  does a class of your own (your `sig/` may omit the superclass Ruby
+  gives it), a gem's class, a relative name such as plain `String`
+  (it may be your own `App::String`), an optional or rest parameter
+  (a call may leave it out), or a block's parameters (the body may
+  never yield). A stale generated signature is the usual cause:
+  regenerate it, or fix the annotation.
+- **Rigor cannot tell: the `.rbs` binds, with an `:info`.** When a
+  position names a type alias, an interface, `self`, a type variable,
+  or a relative class name your project also declares, when Rigor
+  cannot prove two types disjoint (a subclass relation such as
+  `Integer` against `Numeric` included), when the parameter lists are shaped
+  differently but overlap, when the overloads do not pair one to one
+  (they are paired by what they declare, not by their order), or when
+  each side is more precise somewhere, the inline signature is dropped
+  and reported as
+  `plugin.rbs-inline.source-rbs-annotation-not-honoured`, naming the
+  member and the `.rbs` that bound. Make one a refinement of the
+  other, or delete one, to settle it.
+
+`rigor sig-gen --write` produces this overlap on purpose: by default it
+copies each inline declaration into `sig/`, so the generated signature
+is the complete contract a gem ships. An identical copy is quiet, as
+above. When an inline annotation later disagrees with its copy,
+`rigor sig-gen --write` and `--check` refuse the method and exit `1`
+until you make the two agree or pass `--overwrite`, which replaces the
+`sig/` member with the inline declaration. A project whose Steep reads the same
+annotations sets `sig_gen.inline_declared: skip` instead
+([handbook chapter 11](../../handbook/11-sig-gen.md#methods-declared-inline)).
+
+A `%a{rigor:v1:return: …}` or `%a{rigor:v1:param: …}` refinement on an
+inline annotation must also share values with its own declared type:
+`# @rbs %a{rigor:v1:return: positive-int} () -> ::String` is reported as
+`rbs.contradicting-signature` at the annotated file (the same proof rule
+applies, so `-> String` without `::` is left alone).
+
+There is no upstream rule to defer to: rbs merges an inline `.rb`
+declaration and a `.rbs` one into a single class entry and ranks
+neither, so Steep reports the same overlap as a signature error and
+the class fails to build. Rigor keeps the reporting and drops the
+degradation ([ADR-112](../../adr/112-extrbs-comment-channel.md) WD5,
+which replaced [ADR-32](../../adr/32-rbs-inline-comment-ingestion.md)
+WD13's "the `.rbs` always wins") — left to collide, one duplicated
+method costs the class every other method, and each call on it, real
+methods and typos alike, reads `Dynamic[top]`.
 
 Two overlaps this does **not** cover: a `.rbs` that collides with
 *bundled* RBS (Ruby core, stdlib, a gem's signatures) is quarantined
@@ -109,6 +166,136 @@ in silence. Constructs the gem supports and the built-in parser does not —
 `@rbs generic T`, `@rbs!` embedded RBS blocks, `@rbs inherits`, method
 visibility — all work here.
 
+## Same-line annotations
+
+An `%a{…}` annotation can sit on the same line as a method type:
+
+```ruby
+class Reader
+  # @rbs %a{rigor:v1:return: non-empty-string} () -> String
+  def title = "x"
+
+  #: %a{pure} () -> String
+  def label = "x"
+end
+```
+
+This is the spelling the built-in parser and Steep's inline mode accept. The
+gem itself does not: it keeps the annotation and drops the method type in the
+`@rbs` form, and drops the whole `#:` line. Rigor splits the line back into the
+annotation and the method type before the gem's writer runs, so both apply, as
+they do when the annotation has a line of its own
+([ADR-32](../../adr/32-rbs-inline-comment-ingestion.md) WD11). The gem's own
+`rbs-inline --output` is unchanged and still drops them.
+
+When the method type after the annotations does not parse, nothing is split:
+the method types as if no signature had been written, and Rigor reports it — a
+`#:` line under [Unparseable `#:` types](#unparseable--types), and an `@rbs`
+line as `plugin.rbs-inline.source-rbs-annotation-not-honoured` naming the line
+and the text it could not read.
+
+## Unparseable `#:` types
+
+A `#:` line whose type does not parse as RBS is dropped — the signature never
+applies, and the method types as if the line had never been written, not
+merely as if its type were wrong:
+
+```ruby
+class BadRefProbe
+  #: (finite-float) -> String
+  def show(f)
+    f.to_s
+  end
+end
+```
+
+`finite-float` is a [Rigor refinement](../16-rbs-extended-annotations.md)
+name, not an RBS type, and does not belong in an ordinary type position.
+Rigor reports the drop as
+`plugin.rbs-inline.source-rbs-annotation-not-honoured`, naming the line and
+the text that failed to parse, rather than leaving `show` silently `untyped`
+with no diagnostic anywhere. The `# @rbs name: TYPE` tag form of the same
+mistake is a different failure shape — see the next section.
+
+## An unresolvable type name in `# @rbs`
+
+Naming a Rigor refinement (or any other unresolvable name) where an RBS type
+belongs in the `# @rbs name: TYPE` tag form does not drop silently the way
+`#:` does — it takes the whole class down:
+
+```ruby
+class ProbeZZ
+  # @rbs g: finite-float
+  def probe(g)
+    g.to_s
+  end
+end
+```
+
+Upstream's own type parser truncates `finite-float` to `finite` (a hyphen
+cannot continue an RBS type name) before this ever reaches Rigor, so `finite`
+is the only token that reaches `RBS::DefinitionBuilder` — and it names no
+loaded type, so the build for the WHOLE class fails
+(`RBS::NoTypeFoundError`). `probe`, and every other real method on `ProbeZZ`,
+reads `Dynamic[top]`. This surfaces as
+`rbs.coverage.definition-build-failed`, naming the token and, when it is the
+truncated head of a registered refinement name, the `%a{rigor:v1:…}` spelling
+that IS valid today (see
+[RBS::Extended annotations](../16-rbs-extended-annotations.md)).
+
+## Unparseable `# @rbs name:` types
+
+A bounded or parameterised refinement — `Integer[1..10]`, `non-empty-array
+[Integer]` — does not truncate at a hyphen the way `finite-float` does, so it
+does not take the whole class down. In a `# @rbs name: TYPE` position it
+leaves the parameter untyped instead, silently:
+
+```ruby
+class BoundedProbe
+  # @rbs n: Integer[1..10]
+  def probe(n)
+    n
+  end
+end
+```
+
+The gem's grammar makes the colon-and-type optional on this annotation, so a
+`TYPE` it cannot parse leaves the parameter's name recorded and its type
+unset rather than raising — indistinguishable downstream from a parameter
+nobody annotated at all. Rigor reports the drop as
+`plugin.rbs-inline.source-rbs-annotation-not-honoured`, naming the line and
+the text that failed to parse, and points at the `%a{rigor:v1:param:}`
+spelling that carries a refinement like `Integer[1..10]` correctly (see
+[RBS::Extended annotations](../16-rbs-extended-annotations.md)) — the same
+advice the `%a{rigor:v1:…}` pointer above gives for the tag form.
+
+## An unrecognised tag after `@rbs`
+
+The gem recognises a comment as an `@rbs` annotation attempt as soon as it
+sees the word boundary right after `@rbs` — which matches a hyphen, not only
+whitespace or end-of-line:
+
+```ruby
+class TagProbe
+  # @rbs-ext return: non-empty-string
+  # @rbs return: String
+  def name
+    "x"
+  end
+end
+```
+
+`# @rbs-ext …` is inside that net, but nothing in the gem's grammar
+recognises `-ext`, so the gem gives up on the whole paragraph and folds it
+back into an ordinary comment — the neighbouring `# @rbs return: String`
+line still binds, but the `@rbs-ext` line contributes nothing and, before
+this, said nothing either. Rigor reports the drop as
+`plugin.rbs-inline.source-rbs-annotation-not-honoured`, naming the line and
+the comment text — without implying `@rbs-ext` is a recognised tag of any
+kind. A comment that merely mentions `@rbs` in prose, or one that opens with
+a tag not starting with `@rbs` (`# @extrbs …`), is outside the gem's
+detector and stays silent.
+
 ## Configuration
 
 ```yaml

data/docs/manual/plugins/rigor-sidekiq.md

@@ -40,7 +40,7 @@ arguments.
 | `plugin.sidekiq.worker-call` | info | a `Worker.perform_*` call matched a discovered worker's `#perform` arity |
 | `plugin.sidekiq.wrong-arity` | error | the forwarded argument count falls outside `#perform`'s arity envelope (message names the schedule carve-out for `perform_in` / `perform_at`) |
 | `plugin.sidekiq.missing-schedule` | error | `perform_in()` / `perform_at()` called with zero arguments (the schedule is required even when `#perform` takes none) |
-| `plugin.sidekiq.load-error` | warning | worker discovery failed (parse/read error) — once per file |
+| `plugin.sidekiq.load-error` | warning | worker discovery failed (parse/read error) — once per run, on `.rigor.yml` |
 
 ## What it types
 
@@ -144,6 +144,13 @@ added it is 100.
   alternative `klass:` spelling, and a schedule built in Ruby with
   `Sidekiq::Cron::Job.load_from_hash!`, supply no roots — the worker
   stays a `rigor unused` candidate rather than being guessed at.
+- **The "failed to discover workers" warning is run-scoped.** It is
+  a fact about your configuration, not about any one source file, so
+  it is reported once per run on `.rigor.yml` rather than repeated on
+  every analysed file. It is `:warning`, so if you baselined it at its
+  old position that entry no longer matches and the row fails a
+  `--fail-on=warning` run — regenerate with `rigor baseline
+  regenerate`.
 
 ## Plugin internals
 

data/docs/manual/plugins/rigor-sorbet.md

@@ -47,11 +47,27 @@ plugins:
 The plugin is **input-side only**: it translates Sorbet's syntax
 into Rigor's type model. It does **not** run Sorbet's checker,
 ship `sorbet-runtime`, or enforce Sorbet's runtime guarantees.
-When an RBS sig and a Sorbet sig disagree, RBS wins (the Sorbet
-sig may refine but not contradict it). Forms outside the
-translation table (`T.proc`, `T.self_type`, `T::Struct` /
-`T::Enum` subclasses, …) degrade to `Dynamic[top]`. Chapter 10
-documents the full vocabulary and these edges.
+When an RBS sig and a Sorbet sig disagree, call sites get the
+Sorbet sig's return type, and the method's body is checked
+against the RBS return. Forms outside the
+translation table (`T.proc`, `T.self_type`, …) degrade to
+`Dynamic[top]`. Chapter 10 documents the full vocabulary and
+these edges.
+
+The plugin also types the annotation DSL's own expressions
+(`sig`, `params`, `returns`, `void`, `abstract`, `override`,
+`type_member`, `T::Array[...]`, `T::Helpers`/`T::Generic` macros,
+`T::Struct`/`T::Enum` class bodies — `sig` on a plain
+`T::Struct` subclass still needs the subclass's own `extend T::Sig`,
+matching the runtime) through a bundled
+`sorbet-runtime` RBS surface — so the sig DSL no longer reads as
+`Dynamic[top]` on a Sorbet codebase. What it does not model:
+`T::Struct` does not synthesise `prop`-declared readers (a
+`Doc#name` accessor still reads opaque), `include T::Props` does
+not confer the `ClassMethods` surface (only the `< T::Struct`
+subclass path does), and the deeper type-member machinery
+(`T.attached_class` variance, `type_member` bounds) is not
+propagated into call sites.
 
 ## Plugin internals
 

data/exe/rigor

@@ -11,13 +11,28 @@
 # context across the exec. The `none` and `process` (default) strategies
 # need no flag, so this is a no-op for them — behaviour is unchanged
 # unless a project opts into `ruby_box`.
+#
+# Before re-exec'ing, a child Ruby probes whether this Ruby can run
+# Rigor under `RUBY_BOX=1` at all (Rigor::Plugin::BoxProbe — released
+# Rubies through 4.0.7 segfault on Ruby Bug #22260). When it cannot,
+# the request is dropped with a warning and the run proceeds under the
+# configured strategy (`process` by default) instead of crashing.
 rigor_isolation = ENV["RIGOR_PLUGIN_ISOLATION"].to_s
 rigor_wants_box = rigor_isolation == "ruby_box" || !ENV["RIGOR_BOX"].to_s.empty?
 if rigor_wants_box && ENV["RUBY_BOX"].to_s.empty?
-  require "rbconfig"
-  ENV["RUBY_BOX"] = "1"
-  ENV["RIGOR_PLUGIN_ISOLATION"] = "ruby_box" if rigor_isolation.empty?
-  exec(RbConfig.ruby, __FILE__, *ARGV)
+  require_relative "../lib/rigor/plugin/box_probe"
+  if (rigor_box_unsupported = Rigor::Plugin::BoxProbe.unsupported_reason)
+    rigor_box_warning = "rigor: ruby_box plugin isolation is unavailable: #{rigor_box_unsupported}. " \
+                        "Falling back to the configured plugins_isolation strategy (default: process)."
+    # `$stderr.puts`, not `warn`: `-W0` silences `warn`, and this fallback must never be silent.
+    $stderr.puts rigor_box_warning # rubocop:disable Style/StderrPuts
+    ENV.delete("RIGOR_PLUGIN_ISOLATION") if rigor_isolation == "ruby_box"
+    ENV.delete("RIGOR_BOX")
+  else
+    ENV["RUBY_BOX"] = "1"
+    ENV["RIGOR_PLUGIN_ISOLATION"] = "ruby_box" if rigor_isolation.empty?
+    exec(RbConfig.ruby, __FILE__, *ARGV)
+  end
 end
 
 lib = File.expand_path("../lib", __dir__)

data/lib/rigor/analysis/baseline.rb

@@ -275,7 +275,7 @@ module Rigor
         YAML.dump(document)
       end
 
-      # The number of buckets recorded. Useful for the CLI summary on `generate`.
+      # The bucket count the `generate` summary reports.
       def size
         buckets.size
       end

data/lib/rigor/analysis/check_rules/declaration_sourced_guard.rb

@@ -32,9 +32,19 @@ module Rigor
       # `docs/internal-spec/inference-engine.md` § "Declaration-sourced provenance mark (ADR-58)"; keep this
       # comment subordinate to it.
       #
-      # So `marked?` matches exactly the two node shapes the scope actually models and invents no propagation
-      # of its own; anything flow-live keeps firing.
+      # So `marked?` matches exactly the node shapes the scope actually models and invents no propagation of its
+      # own; anything flow-live keeps firing.
+      #
+      # Issue #1362 adds a third carrier, a global still on its program-global seed, which joins the non-nil part of
+      # the declared type of a global Ruby's own signatures declare with the file's writes (ADR-117 Decision point
+      # 2: never warn that a value might deviate from the idiom). Its declared members are the declaration-sourced
+      # part. The consumers judge such a value by the file's writes ({.written_type}, {.withholds_nil?}), and a
+      # value that mixes it with something else without the declared members the file never writes
+      # ({.declared_only_rejection?}), so a report the writes alone earn still fires.
       module DeclarationSourcedGuard
+        NO_GLOBALS = [].freeze
+        private_constant :NO_GLOBALS
+
         module_function
 
         # True when `node` is a direct read of a binding whose optionality is purely declaration-sourced. Any
@@ -44,9 +54,164 @@ module Rigor
           case node
           when Prism::InstanceVariableReadNode then scope.declaration_sourced?(:ivar, node.name)
           when Prism::LocalVariableReadNode then scope.declaration_sourced?(:local, node.name)
+          when Prism::GlobalVariableReadNode then scope.declaration_sourced?(:global, node.name)
           else false
           end
         end
+
+        # The globals whose declared seeds `node` still reads, empty for none: a read of a marked global, or of a
+        # local copied from one or more (`sep = $/`, `Scope#declaration_sourced_global_copies`), bare or in
+        # parentheses (`($stdout)`).
+        def global_sources(node, scope)
+          node = unparenthesised(node)
+          case node
+          when Prism::GlobalVariableReadNode
+            scope.declaration_sourced?(:global, node.name) ? [node.name] : NO_GLOBALS
+          when Prism::LocalVariableReadNode
+            scope.declaration_sourced_global_copies(node.name)
+          else NO_GLOBALS
+          end
+        end
+
+        # The globals a local written from `value` copies the declared seeds of, empty for none: a read of a marked
+        # global, bare or in parentheses (`sep = ($/)`), or a bare read of a local that copies some (`s = sep`).
+        # Unlike an ivar copy's, this mark follows bare local-to-local copies; a method result (`$/.dup`) or a
+        # container element (`[$/].each { |s| … }`) carries none, as ADR-58's one-hop boundary has it.
+        def copied_globals(value, scope)
+          return scope.declaration_sourced_global_copies(value.name) if value.is_a?(Prism::LocalVariableReadNode)
+
+          read = unparenthesised(value)
+          return NO_GLOBALS unless read.is_a?(Prism::GlobalVariableReadNode) &&
+                                   scope.declaration_sourced?(:global, read.name)
+
+          [read.name]
+        end
+
+        # `node` with its enclosing parentheses taken off while they hold a single expression.
+        def unparenthesised(node)
+          while node.is_a?(Prism::ParenthesesNode)
+            body = node.body
+            break unless body.is_a?(Prism::StatementsNode) && body.body.size == 1
+
+            node = body.body.first
+          end
+          node
+        end
+
+        # The union of the file's own writes to the globals `node` reads the seeds of ({.global_sources}), or nil.
+        def written_type(node, scope)
+          sources = global_sources(node, scope)
+          return nil if sources.empty?
+
+          written = sources.map { |source| scope.program_globals[source] }
+          written.include?(nil) ? nil : Type::Combinator.union(*written)
+        end
+
+        # True when a `nil` in `node`'s type is not diagnostic fuel: for a global's seed or its copy, when the file
+        # never writes `nil` to the global, so the declaration alone contributes it; otherwise when `node` carries
+        # the ADR-58 mark.
+        def withholds_nil?(node, scope)
+          written = written_type(node, scope)
+          return marked?(node, scope) if written.nil?
+
+          !nil_bearing?(written)
+        end
+
+        # Issue #1362 — true when every member of `type` that `expected` rejects is a declared member of a builtin
+        # global this file writes and joins ({#declared_only_members}), so the rejection rests on the join alone. The
+        # argument and return gates read it for a value that mixes such a global with something else
+        # (`c ? $stdout : StringIO.new`), which the ADR-58 mark does not follow. It is a type-level reading: it also
+        # withholds a rejection of such a member that comes from elsewhere in the file (`STDOUT` passed where a
+        # `StringIO` is required, in a file that writes `$stdout`).
+        #
+        # Otherwise the value with those members taken out of every union inside it ({#without_declared_only}) is
+        # handed to the block, which answers whether the caller's rule accepts it: the value as it was before the
+        # join, one level into a container it builds as well (`[$stdout]` or `{ io: $stdout }` passed where an
+        # `Array[StringIO]` is required), and with a `nil` the file writes judged as the rule judges a `nil`.
+        def declared_only_rejection?(type, expected, scope)
+          declared_only = declared_only_members(scope)
+          return false if declared_only.empty?
+
+          members = type.is_a?(Type::Union) ? type.members : [type]
+          rejected = members.select { |member| Inference::Acceptance.accepts(expected, member, mode: :gradual).no? }
+          return false if rejected.empty?
+          return true if rejected.all? { |member| declared_only.include?(member) }
+
+          stripped = without_declared_only(type, declared_only)
+          !stripped.equal?(type) && yield(stripped)
+        end
+
+        # `type` with each member of `declared_only` taken out of every union in it, through tuples, hash shapes and
+        # generic arguments; a union with nothing else left keeps its members. Answers `type` itself when nothing
+        # was taken out.
+        def without_declared_only(type, declared_only)
+          case type
+          when Type::Union then union_without_declared_only(type, declared_only)
+          when Type::Tuple
+            elements = type.elements.map { |element| without_declared_only(element, declared_only) }
+            elements == type.elements ? type : Type::Combinator.tuple_of(*elements)
+          when Type::HashShape
+            pairs = type.pairs.transform_values { |value| without_declared_only(value, declared_only) }
+            pairs == type.pairs ? type : rebuild_hash_shape(type, pairs)
+          when Type::Nominal
+            args = type.type_args.map { |arg| without_declared_only(arg, declared_only) }
+            args == type.type_args ? type : Type::Combinator.nominal_of(type.class_name, type_args: args)
+          else type
+          end
+        end
+
+        def union_without_declared_only(union, declared_only)
+          kept = union.members.reject { |member| declared_only.include?(member) }
+          kept = union.members if kept.empty?
+          rebuilt = kept.map { |member| without_declared_only(member, declared_only) }
+          rebuilt == union.members ? union : Type::Combinator.union(*rebuilt)
+        end
+
+        def rebuild_hash_shape(shape, pairs)
+          Type::Combinator.hash_shape_of(
+            pairs, required_keys: shape.required_keys, optional_keys: shape.optional_keys,
+                   read_only_keys: shape.read_only_keys, extra_keys: shape.extra_keys
+          )
+        end
+
+        # For each builtin global this file writes and joins, the non-nil members of its declared type that the file's
+        # writes to that global do not hold (`IO` after `$stdout = StringIO.new`, nothing after `$stderr = STDERR`),
+        # gathered over the globals. A declared literal also counts in its class form, which a method called on the
+        # joined union returns: `$VERBOSE.itself` reads `FalseClass | TrueClass` after `$VERBOSE = true`.
+        def declared_only_members(scope)
+          seeds = scope.discovery.program_global_seeds
+          return NO_GLOBALS if seeds.empty?
+
+          seeds.keys.flat_map do |name|
+            written = type_members(scope.program_globals[name])
+            type_members(scope.environment.global_for_name(name, builtin: true))
+              .reject { |member| nil_bearing?(member) }
+              .flat_map { |member| [member, *class_form(member)] }
+              .reject { |member| written.include?(member) }
+          end.uniq
+        end
+
+        def class_form(member)
+          return NO_GLOBALS unless member.is_a?(Type::Constant)
+
+          [Type::Combinator.nominal_of(member.value.class.name)]
+        end
+
+        def type_members(type)
+          return NO_GLOBALS if type.nil?
+
+          type.is_a?(Type::Union) ? type.members : [type]
+        end
+
+        def nil_bearing?(type)
+          members = type.is_a?(Type::Union) ? type.members : [type]
+          members.any? do |member|
+            (member.is_a?(Type::Constant) && member.value.nil?) ||
+              (member.is_a?(Type::Nominal) && member.class_name == "NilClass")
+          end
+        end
+        private_class_method :nil_bearing?, :unparenthesised, :declared_only_members, :type_members, :class_form,
+                             :without_declared_only, :union_without_declared_only, :rebuild_hash_shape
       end
     end
   end