rigortype 0.3.8 → 0.4.0

data/plugins/rigor-sorbet/lib/rigor/plugin/sorbet/absurd_recognizer.rb

@@ -37,8 +37,7 @@ module Rigor
       #   run, so the same Prism node object is seen in both the `dynamic_return` rule and
       #   `diagnostics_for_file`.
       module AbsurdRecognizer
-        # @param call_node [Prism::CallNode]
-        # @return [Boolean] true when `call_node` is `T.absurd(x)`.
+        # @return true when `call_node` is `T.absurd(x)`.
         def self.absurd_call?(call_node)
           return false unless call_node.is_a?(Prism::CallNode)
           return false unless call_node.name == :absurd
@@ -50,9 +49,7 @@ module Rigor
           arguments&.size == 1
         end
 
-        # @param call_node [Prism::CallNode]
-        # @param scope [Rigor::Scope, nil]
-        # @return [Boolean] true when the discriminant has been narrowed to `bot` (the branch is
+        # @return true when the discriminant has been narrowed to `bot` (the branch is
         #   unreachable, so `T.absurd` is correct). The caller suppresses the `absurd-reachable` diagnostic
         #   in this case.
         def self.exhaustive?(call_node, scope)

data/plugins/rigor-sorbet/lib/rigor/plugin/sorbet/assertion_recognizer.rb

@@ -53,10 +53,7 @@ module Rigor
 
         module_function
 
-        # @param call_node [Prism::CallNode]
-        # @param scope [Rigor::Scope]
-        # @param plugin_id [String] used for the contribution's `provenance.source_family`.
-        # @return [Rigor::FlowContribution, nil]
+        # @param plugin_id — used for the contribution's `provenance.source_family`.
         def recognize(call_node:, scope:, plugin_id:)
           return nil unless TypeTranslator.sorbet_t_namespaced?(call_node.receiver)
           return nil unless SORBET_ASSERTIONS.include?(call_node.name)

data/plugins/rigor-sorbet/lib/rigor/plugin/sorbet/catalog.rb

@@ -23,7 +23,6 @@ module Rigor
           @frozen_after_build = false
         end
 
-        # @param signature [MethodSignature]
         def record(signature)
           raise "Catalog already finalised" if @frozen_after_build
 
@@ -31,10 +30,9 @@ module Rigor
           @entries[key] = signature
         end
 
-        # @param class_name [String] the class / module that carries the mixin (`class Post; include Foo;
+        # @param class_name — the class / module that carries the mixin (`class Post; include Foo;
         #   end` records under `"Post"`).
-        # @param kind [:include, :extend]
-        # @param module_name [String] the textual name of the mixed-in module as it appeared at the
+        # @param module_name — the textual name of the mixed-in module as it appeared at the
         #   include / extend site (`"Foo"`, `"Foo::Bar"`, `"::Foo"`).
         def record_mixin(class_name:, kind:, module_name:)
           raise "Catalog already finalised" if @frozen_after_build
@@ -55,13 +53,11 @@ module Rigor
           freeze
         end
 
-        # @return [MethodSignature, nil]
         def lookup(class_name:, method_name:, kind:)
           @entries[key_for(class_name, method_name, kind)]
         end
 
-        # @param class_name [String]
-        # @return [Hash{Symbol => Array<String>}] frozen mapping `{ include: [...], extend: [...] }`.
+        # @return frozen mapping `{ include: [...], extend: [...] }`.
         #   Returns {EMPTY_MIXINS} when no mixins were recorded.
         def mixins_for(class_name)
           @mixins[class_name] || EMPTY_MIXINS
@@ -77,8 +73,6 @@ module Rigor
         # static assertion vocabulary), and the precise `(class, kind)` lookup stays in the rule block.
         # Computed fresh per call — the plugin memoises the resolved set, and `freeze!` freezes the
         # catalog itself so a lazy memo ivar here would raise.
-        #
-        # @return [Array<Symbol>]
         def method_names
           @entries.keys.map { |key| key[1] }.uniq
         end

data/plugins/rigor-sorbet/lib/rigor/plugin/sorbet/catalog_walker.rb

@@ -26,10 +26,10 @@ module Rigor
 
         module_function
 
-        # @param root [Prism::Node] the file's program node.
-        # @param catalog [Catalog] mutable; signatures are recorded into it.
-        # @param path [String] file path used for diagnostic provenance.
-        # @return [Array<ParseError>] errors observed during the walk; empty when the file is sig-clean.
+        # @param root — the file's program node.
+        # @param catalog — mutable; signatures are recorded into it.
+        # @param path — file path used for diagnostic provenance.
+        # @return errors observed during the walk; empty when the file is sig-clean.
         def walk(root:, catalog:, path:)
           state = State.new(catalog: catalog, path: path)
           walk_node(root, state, lexical_path: [], in_singleton_class: false)

data/plugins/rigor-sorbet/lib/rigor/plugin/sorbet/sig_parser.rb

@@ -44,8 +44,7 @@ module Rigor
 
         module_function
 
-        # @param sig_call [Prism::CallNode] the `sig { ... }` / `sig do ... end` call.
-        # @return [ParseResult, ParseError]
+        # @param sig_call — the `sig { ... }` / `sig do ... end` call.
         def parse(sig_call)
           return ParseError.new(reason: :no_block, node: sig_call) if sig_call.block.nil?
 

data/plugins/rigor-sorbet/lib/rigor/plugin/sorbet/sigil_detector.rb

@@ -30,8 +30,7 @@ module Rigor
 
         module_function
 
-        # @param contents [String] raw file contents.
-        # @return [Symbol] one of {VALID_LEVELS}; defaults to {DEFAULT_LEVEL} for sigil-less or
+        # @return one of {VALID_LEVELS}; defaults to {DEFAULT_LEVEL} for sigil-less or
         #   malformed-sigil files.
         def detect(contents)
           return DEFAULT_LEVEL if contents.nil? || contents.empty?
@@ -52,14 +51,13 @@ module Rigor
           DEFAULT_LEVEL
         end
 
-        # @param level [Symbol]
-        # @return [Boolean] true when `# typed: ignore`. The harvest pipeline calls this to short-circuit
+        # @return true when `# typed: ignore`. The harvest pipeline calls this to short-circuit
         #   walking the file's AST.
         def ignored?(level)
           level == :ignore
         end
 
-        # @return [Boolean] true when `level` is at or above the `# typed: true` mark. Used by the
+        # @return true when `level` is at or above the `# typed: true` mark. Used by the
         #   `enforce_sigil` config gate (default `true`): with the gate on, only files marked `:true` /
         #   `:strict` / `:strong` contribute their sigs to the catalog. The `:false` (and sigil-less)
         #   levels still get walked (so RBI files outside the project can be loaded regardless), but their

data/plugins/rigor-sorbet/lib/rigor/plugin/sorbet/type_translator.rb

@@ -52,8 +52,7 @@ module Rigor
 
         module_function
 
-        # @param node [Prism::Node, nil]
-        # @return [Rigor::Type] never `nil`; unrecognised forms degrade to `Type::Combinator.untyped`.
+        # @return never `nil`; unrecognised forms degrade to `Type::Combinator.untyped`.
         def translate(node)
           return Rigor::Type::Combinator.untyped if node.nil?
 
@@ -67,7 +66,6 @@ module Rigor
           end
         end
 
-        # @param node [Prism::ConstantReadNode]
         def translate_constant_read(node)
           name = node.name.to_s
           return Rigor::Type::Combinator.untyped if name.empty?
@@ -75,7 +73,6 @@ module Rigor
           Rigor::Type::Combinator.nominal_of(name)
         end
 
-        # @param node [Prism::ConstantPathNode]
         def translate_constant_path(node)
           name = constant_path_name(node)
           return degraded if name.nil?
@@ -233,7 +230,12 @@ module Rigor
 
             pairs << [element.key.unescaped.to_sym, translate(element.value)]
           end
-          Rigor::Type::Combinator.hash_shape_of(pairs)
+          # `.to_h`: `hash_shape_of` validates its argument is a Hash and raises `ArgumentError` on the
+          # array-of-pairs form, so `sig { returns({name: String}) }` degraded to `Dynamic[top]` through
+          # the plugin's rescue instead of producing a shape. Found by #673, when relaxing
+          # `call.argument-type-mismatch` to check the positional arguments of keyword-bearing
+          # signatures made the call site visible.
+          Rigor::Type::Combinator.hash_shape_of(pairs.to_h)
         end
 
         # Renders a constant-path node (`Foo::Bar`, `::Foo::Bar`) as a `::`-joined String. Mirrors the

data/plugins/rigor-sorbet/lib/rigor/plugin/sorbet.rb

@@ -29,6 +29,14 @@ module Rigor
     # The {TypeTranslator} table documents coverage. Most of Sorbet's vocabulary translates; remaining
     # gaps (`T.proc`, `T::Struct` subclasses, `T.attached_class`, etc.) degrade silently to `Dynamic[top]`.
     #
+    # Issue #1097 — the plugin also ships `sig/sorbet.rbs`, a bundled declaration of the annotation DSL
+    # surface itself: `T`'s type-expression functions, the `T::X[...]` constructors, `T::Sig`'s `sig`
+    # verb (reached via the manifest `rbs_complete_extends:` bridge over `extend T::Sig`), the
+    # `DeclBuilder` the sig block `instance_eval`s on (via `block_as_methods:`), and the
+    # `T::Struct` / `T::Enum` family (via `rbs_complete_ancestors:`). The value-side assertions
+    # (`T.let`/`T.cast`/`T.must`/…) stay recogniser-owned — RBS cannot express "return the asserted
+    # type" — and `T`'s declared surface is intentionally partial behind `open_receivers:`.
+    #
     # Architecture: per-run `Catalog` is built lazily on first access by walking every configured `paths:`
     # entry's `.rb` files plus every `rbi_paths:` entry's `.rbi` files (slice 4) via the plugin's
     # `IoBoundary`. The catalog is frozen after the first build and consulted by the `dynamic_return` rule
@@ -57,6 +65,7 @@ module Rigor
     class Sorbet < Rigor::Plugin::Base
       manifest(
         id: "sorbet",
+        target_gems: ["sorbet-runtime"],
         version: "0.1.0",
         description: "Ingests Sorbet `sig` blocks as method-signature contributions.",
         config_schema: {
@@ -69,7 +78,43 @@ module Rigor
           # effect of recursing into the parent root.
           "rbi_paths" => { kind: :array, default: ["sorbet/rbi"] },
           "enforce_sigil" => { kind: :boolean, default: true }
-        }
+        },
+        # #1097 — bundled sorbet-runtime DSL surface (`sig/sorbet.rbs`). `sig` itself reaches the
+        # class object through `extend T::Sig` (or the `< T::ImmutableStruct` / `< T::Enum`
+        # family, which carry the edge themselves), which is
+        # why `rbs_complete_extends:` — the extend-edge allow-list — carries `T::Sig` /
+        # `T::Helpers` / `T::Generic`, and `rbs_complete_ancestors:` carries the Struct/Enum family
+        # for the subclass bridge.
+        signature_paths: ["sig"],
+        rbs_complete_extends: %w[T::Sig T::Helpers T::Generic],
+        rbs_complete_ancestors: %w[T::Struct T::InexactStruct T::ImmutableStruct T::Enum],
+        # `sig { ... }` bodies are `instance_eval`'d on a `DeclBuilder`
+        # (`T::Private::Methods._run_builder`), so `params` / `returns` / `void` resolve on the
+        # builder, not the enclosing class. `T::Sig::WithoutRuntime.sig` is the direct-call twin —
+        # a singleton method on the module, matching by name equality.
+        block_as_methods: [
+          Rigor::Plugin::Macro::BlockAsMethod.new(
+            receiver_constraint: "T::Sig",
+            method_names: %i[sig],
+            self_type: "T::Private::Methods::DeclBuilder"
+          ),
+          Rigor::Plugin::Macro::BlockAsMethod.new(
+            receiver_constraint: "T::Sig::WithoutRuntime",
+            method_names: %i[sig],
+            self_type: "T::Private::Methods::DeclBuilder"
+          )
+        ],
+        # The declared surface is deliberately partial — `T` is an open module whose runtime
+        # surface is much larger than the DSL (version-dependent internals, `T::Private::*`,
+        # `T::Configuration`, `T::Utils`). Open receivers keep an unmodelled `T.something` opaque
+        # rather than a `call.undefined-method` false positive. `DeclBuilder` is NOT open —
+        # `sig { typo }` is a real bug and stays a diagnostic.
+        open_receivers: %w[T T::Sig T::Sig::WithoutRuntime T::Helpers T::Generic
+                           T::Utils T::Configuration T::Private T::Private::Methods
+                           T::Props T::Props::ClassMethods T::Props::CustomType
+                           T::Types T::Types::Base T::Array T::Hash T::Set
+                           T::Enumerable T::Enumerator T::Range T::Class
+                           T::InexactStruct T::Struct T::ImmutableStruct T::Enum]
       )
 
       def init(services)
@@ -440,13 +485,13 @@ module Rigor
       # Frozen empty bundle used when the `:catalog` producer failed (e.g. a project I/O error) so downstream
       # reads see a well-formed shape rather than nil.
       EMPTY_CATALOG_BUNDLE = { catalog: Catalog.new.freeze!, sigil_by_path: {}, parse_errors_by_path: {} }.freeze
+      Ractor.make_shareable(EMPTY_CATALOG_BUNDLE)
       private_constant :EMPTY_CATALOG_BUNDLE
 
-      # @param root [String] directory or single file.
-      # @param catalog [Catalog]
-      # @param sigil_by_path [Hash{String=>Symbol}] accumulator: harvested file → detected sigil level.
-      # @param parse_errors_by_path [Hash{String=>Array<Hash>}] accumulator: file → `{kind:,line:,column:}` tuples.
-      # @param extensions [Array<String>] file extensions to accept (e.g. `[".rb"]` for project source,
+      # @param root — directory or single file.
+      # @param sigil_by_path — accumulator: harvested file → detected sigil level.
+      # @param parse_errors_by_path — accumulator: file → `{kind:,line:,column:}` tuples.
+      # @param extensions — file extensions to accept (e.g. `[".rb"]` for project source,
       #   `[".rbi"]` for Sorbet RBI tree).
       def harvest_path(root, catalog, sigil_by_path, parse_errors_by_path, extensions)
         absolute = canonicalize(root)

data/plugins/rigor-sorbet/sig/sorbet.rbs

@@ -0,0 +1,277 @@
+# Bundled RBS for the sorbet-runtime annotation DSL (issue #1097).
+#
+# sorbet-runtime ships RBI, not RBS, so none of the annotation surface (`T`, `T::Sig`, the
+# `DeclBuilder` behind `sig { ... }`, the `T::Array[...]` constructors, the `T::Helpers` /
+# `T::Generic` class macros) resolves for the analyzer. This file declares that surface so the
+# DSL *expressions themselves* type; the plugin's `AssertionRecognizer` continues to own the
+# value-sensitive calls (`T.let` / `T.cast` / `T.must` / `T.bind` / `T.assert_type!` /
+# `T.reveal_type` / `T.unsafe`) ahead of this RBS — the signatures here deliberately agree with
+# it (`T.unsafe` stays `untyped`, `T.bind` returns `nil`) for the cases the recognizer declines.
+#
+# Provenance (docs/agents/type-authoring.md): `rigor sig-gen` cannot produce this file — the DSL
+# methods are installed by `Module#extend` hooks and `instance_eval` in sorbet-runtime's source
+# (sorbet-runtime 0.5.11766, `lib/types/{sig,_types,generic,helpers,struct,enum}.rb` and
+# `lib/types/private/methods/decl_builder.rb`), so every entry was hand-derived by reading that
+# source. Members that do not exist at that version's runtime location are deliberately absent.
+#
+# Two Rigor-side mechanisms complete the picture (manifest fields):
+#
+# - `rbs_complete_extends:` — `extend T::Sig` in a class/module body is what puts `sig` on the
+#   class object's singleton; the dispatch bridge resolves those calls through the module's
+#   instance surface declared here.
+# - `block_as_methods:` — `sig`'s block is `instance_eval`'d on a `DeclBuilder`
+#   (`T::Private::Methods.declare_sig` → `DeclBuilder#instance_eval`), so `sig` bodies bind
+#   `self` to `T::Private::Methods::DeclBuilder`, NOT to the enclosing class.
+
+module T
+  # `T::Boolean` is a runtime constant (`T.any(TrueClass, FalseClass)` → a `T::Types::Union`
+  # instance), not a module — it appears in `params`/`returns` argument position as a const read.
+  Boolean: ::T::Types::Union
+
+  # The type-ASSERTION functions (`T.let`, `T.cast`, `T.assert_type!`, `T.bind`, `T.must`,
+  # `T.must_because`, `T.reveal_type`, `T.absurd`, `T.unsafe`) are deliberately NOT declared here.
+  # Their static return is the *asserted* type (the second argument, translated) or the nil-stripped
+  # inner type — semantics RBS cannot express — so the plugin's `AssertionRecognizer` /
+  # `AbsurdRecognizer` owns them ahead of dispatch, and a declined call degrades through `T`'s
+  # `open_receivers:` entry to opaque rather than a wrong `X` reading.
+
+  # Type-expression constructors — used in `params`/`returns` argument position.
+  def self.nilable: (untyped type) -> ::T::Types::Base
+  def self.untyped: () -> ::T::Types::Base
+  def self.noreturn: () -> ::T::Types::Base
+  def self.anything: () -> ::T::Types::Base
+  def self.all: (untyped type_a, untyped type_b, *untyped types) -> ::T::Types::Base
+  def self.any: (untyped type_a, untyped type_b, *untyped types) -> ::T::Types::Base
+  def self.class_of: (untyped arg) -> ::T::Types::Base
+  def self.self_type: () -> ::T::Types::Base
+  def self.attached_class: () -> ::T::Types::Base
+  def self.type_parameter: (::Symbol name) -> ::T::Types::TypeParameter
+  # `type=nil, &blk` — the positional form is a kept-for-migration legacy path (`_types.rb`);
+  # the block form wraps in `T::Private::Types::TypeAlias`.
+  def self.type_alias: (?untyped type) ?{ () -> untyped } -> ::T::Types::Base
+
+  # `T.proc` returns a DeclBuilder in `Modes.proc` (`T::Private::Methods.start_proc`), so the
+  # `T.proc.params(x: Integer).returns(String)` chain resolves through the same builder surface.
+  def self.proc: () -> ::T::Private::Methods::DeclBuilder
+end
+
+# `T::Sig` is a mixin a class EXTENDS (`extend T::Sig`) to gain the class-level `sig` verb —
+# sorbet-runtime does not patch `Module`. `sig` itself returns nil at runtime
+# (`declare_sig` stores the DeclarationBlock and returns nil).
+module T::Sig
+  def sig: (?untyped arg0) ?{ () -> untyped } -> nil
+
+  # `T::Sig::WithoutRuntime.sig { ... }` is a no-op shim for contexts where the runtime wrapper
+  # cannot be installed; it is called ON the module, so `sig` here is a module-singleton method.
+  # `extend T::Sig::WithoutRuntime` installs nothing at runtime, so no instance `sig` is declared.
+  module WithoutRuntime
+    def self.sig: (?untyped arg0) ?{ () -> untyped } -> nil
+  end
+end
+
+# The builder `sig`'s block is `instance_eval`'d on (`DeclBuilder#instance_eval(&blk)` via
+# `T::Private::Methods._run_builder`). Every DSL method returns `self` so the
+# `params(...).returns(...).checked(:always)` chain keeps typing.
+class T::Private::Methods::DeclBuilder
+  def params: (*untyped unused_positional_params, **untyped params) -> self
+  def returns: (untyped type) -> self
+  def void: () -> self
+  def bind: (untyped type) -> self
+  def checked: (untyped level) -> self
+  def on_failure: (*untyped args) -> self
+  def abstract: () -> self
+  def final: () -> self
+  def override: (?allow_incompatible: bool | Symbol) -> self
+  def overridable: () -> self
+  def type_parameters: (*untyped names) -> self
+end
+
+# The `T::X[...]` type constructors are modules with a singleton `[]` (`_types.rb`), returning the
+# corresponding `T::Types::TypedX` instance. The carriers below exist so the constructor's return
+# reads as a real nominal rather than `Dynamic[top]`.
+module T::Array
+  def self.[]: (untyped type) -> ::T::Types::TypedArray
+end
+
+module T::Hash
+  def self.[]: (untyped keys, untyped values) -> ::T::Types::TypedHash
+end
+
+module T::Set
+  def self.[]: (untyped type) -> ::T::Types::TypedSet
+end
+
+module T::Enumerable
+  def self.[]: (untyped type) -> ::T::Types::TypedEnumerable
+end
+
+module T::Enumerator
+  def self.[]: (untyped type) -> ::T::Types::TypedEnumerator
+end
+
+module T::Range
+  def self.[]: (untyped type) -> ::T::Types::TypedRange
+end
+
+module T::Class
+  def self.[]: (untyped type) -> ::T::Types::TypedClass
+end
+
+# Carrier classes for the `T::X[...]` constructors and the `T.*` type-expression functions. The
+# internal `T::Types::*` class names are the runtime classes (`types/types/*.rb`).
+module T::Types
+  class Base
+  end
+
+  class TypedArray < Base
+  end
+
+  class TypedHash < Base
+  end
+
+  class TypedSet < Base
+  end
+
+  class TypedEnumerable < Base
+  end
+
+  class TypedEnumerator < Base
+  end
+
+  class TypedRange < Base
+  end
+
+  class TypedClass < Base
+  end
+
+  class Union < Base
+  end
+
+  class Intersection < Base
+  end
+
+  class TypeParameter < Base
+  end
+
+  class TypeMember < Base
+  end
+
+  class TypeTemplate < Base
+  end
+
+  class Proc < Base
+  end
+end
+
+# `extend T::Helpers` installs the class/module declaration macros (`abstract!`, `interface!`,
+# `final!`, `sealed!`, `requires_ancestor`, `mixes_in_class_methods`). All return void-ish values
+# from `T::Private::{Abstract,Final,Sealed}` bookkeeping (`helpers.rb`).
+module T::Helpers
+  def abstract!: () -> void
+  def interface!: () -> void
+  def final!: () -> void
+  def sealed!: () -> void
+  def mixes_in_class_methods: (::Module mod, *::Module mods) -> void
+  def requires_ancestor: () { () -> untyped } -> void
+end
+
+# `extend T::Generic` installs the type-member macros — `Elem = type_member` is the common shape
+# (`generic.rb`). `[]` is the generic-application stub (`def [](*types); self; end`).
+module T::Generic
+  # `generic.rb` — `extend T::Generic` alone also installs the helper macros: the module
+  # `include`s `T::Helpers` (and `Kernel`), so its instance surface carries `abstract!` et al.
+  include T::Helpers
+
+  def []: (*untyped types) -> self
+  def type_member: (?untyped variance) ?{ () -> untyped } -> ::T::Types::TypeMember
+  def type_template: (?untyped variance) ?{ () -> untyped } -> ::T::Types::TypeTemplate
+  def has_attached_class!: (?untyped variance) ?{ () -> untyped } -> void
+end
+
+# `T::Props` is the property mixin; its `included` hook `extend`s the includer with
+# `ClassMethods` (`mixes_in_class_methods`), which is where `prop` / `const` live. The hook itself
+# is not modelled — `include T::Props` alone does not put `prop` on the class in this
+# declaration either — but the `T::Struct` family below declares the same `extend` edges directly,
+# matching the runtime outcome for `< T::Struct` subclasses.
+module T::Props
+  module ClassMethods
+    def prop: (::Symbol name, untyped cls, **untyped rules) -> void
+    def const: (::Symbol name, untyped cls_or_args, **untyped args) -> void
+    def props: () -> ::Hash[untyped, untyped]
+    def plugins: () -> ::Array[untyped]
+    def decorator: () -> ::T::Props::Decorator
+    def decorator_class: () -> ::Class
+    def validate_prop_value: (untyped prop, untyped val) -> void
+    def plugin: (untyped mod) -> void
+  end
+
+  class Decorator
+  end
+
+  module CustomType
+  end
+
+  module Serializable
+    # `serializable.rb` — lifted onto includers via `mixes_in_class_methods`.
+    module ClassMethods
+      def prop_by_serialized_forms: () -> ::Hash[untyped, untyped]
+      def from_hash: (untyped hash, ?bool strict) -> untyped
+      def from_hash!: (untyped hash) -> untyped
+    end
+  end
+
+  module Plugin
+    # `plugin.rb` — `mixes_in_class_methods(ClassMethods)`; `included` re-registers the plugin
+    # (`child.plugin(self)`), which is what extends `plugin::ClassMethods` onto the target.
+    module ClassMethods
+      def included: (untyped child) -> void
+    end
+  end
+end
+
+# The `T::Struct` family. `struct.rb` has `T::InexactStruct` `include T::Props` (+Serializable,
+# +Constructor); the `mixes_in_class_methods` hooks extend `T::Props::ClassMethods` (then the
+# registered `T::Props::Plugin::ClassMethods`) and `T::Props::Serializable::ClassMethods` onto the
+# class — verified against the runtime singleton ancestry. Neither `T::Sig` nor `T::Helpers` is
+# extended here: `sig` inside a `class Doc < T::Struct` body raises at runtime unless the subclass
+# adds `extend T::Sig` itself (dependabot's `TokenBucket` does exactly that). Only
+# `T::ImmutableStruct` extends `T::Sig` (`struct.rb` — it annotates its own `initialize`). The
+# edges are declared directly so subclasses resolve `prop` / `const` / `from_hash` through the
+# `rbs_complete_ancestors` superclass bridge.
+class T::InexactStruct
+  extend T::Props::ClassMethods
+  extend T::Props::Plugin::ClassMethods
+  extend T::Props::Serializable::ClassMethods
+end
+
+class T::Struct < T::InexactStruct
+end
+
+class T::ImmutableStruct < T::InexactStruct
+  extend T::Sig
+end
+
+# `T::Enum` — `enum.rb` `extend`s `T::Sig` and `T::Props::CustomType`; `enums` `yield`s its block
+# so `X = new` inside keeps the subclass's class-object self.
+class T::Enum
+  extend T::Sig
+  extend T::Props::CustomType
+
+  def self.enums: () { () -> untyped } -> void
+  def serialize: () -> ::String
+end
+
+# Namespace-only declarations so bare const reads (`T::Utils`, `T::Configuration`,
+# `T::Private::Methods`) type as `Singleton[...]` instead of `Dynamic[top]`. Their singleton
+# surface is intentionally NOT modelled — they are covered by `open_receivers:` so calls on them
+# degrade to opaque rather than firing `call.undefined-method` on an unmodelled private API.
+module T::Utils
+end
+
+module T::Configuration
+end
+
+module T::Private
+  module Methods
+  end
+end

data/plugins/rigor-statesman/lib/rigor/plugin/statesman.rb

@@ -43,6 +43,7 @@ module Rigor
     class Statesman < Rigor::Plugin::Base
       manifest(
         id: "statesman",
+        target_gems: ["statesman"],
         version: "0.1.0",
         description: "Validates state-machine transition references against declared states.",
         config_schema: {

data/sig/rigor/analysis/baseline.rbs

@@ -6,26 +6,88 @@ module Rigor
       class LoadError < ::StandardError
       end
 
+      # Tuple-shaped bucket key so rule-ID rows and message-pattern rows coexist: `message_regex` is
+      # `nil` for rule-ID rows and a `Regexp` for message-pattern rows; `rule` and `file` are always
+      # present (parse_row raises without them; the generator's group key carries both). `count`
+      # intentionally shadows `Struct#count` — PHPStan-compatible field name.
+      class Bucket < ::Struct[untyped]
+        # sig-gen gap: #1183 — Struct member types are not inferred from construction sites; every
+        # member row in this class (and the keyword ctor below) is hand-written.
+        def file: () -> String
+        # sig-gen gap: #1183 — as above.
+        def rule: () -> String
+        # sig-gen gap: #1183 — as above.
+        def message_regex: () -> Regexp?
+        # sig-gen gap: #1183 — as above.
+        def count: () -> Integer
+        # sig-gen gap: #1183 — as above.
+        def file=: (String) -> String
+        # sig-gen gap: #1183 — as above.
+        def rule=: (String) -> String
+        # sig-gen gap: #1183 — as above.
+        def message_regex=: (Regexp?) -> Regexp?
+        # sig-gen gap: #1183 — as above.
+        def count=: (Integer) -> Integer
+        # sig-gen gap: #1183 — as above.
+        def self.new: (?file: String, ?rule: String, ?message_regex: Regexp?, ?count: Integer) -> instance
+        # sig-gen gap: #1183 — as above.
+        def self.[]: (?file: String, ?rule: String, ?message_regex: Regexp?, ?count: Integer) -> instance
+      end
+
+      # One bucket's drift state for `audit`. `status` is the four-way verdict `status_for` returns;
+      # `delta` is `actual_count - bucket.count` (positive = over threshold).
+      class DriftRow < ::Struct[untyped]
+        # sig-gen gap: #1183 — Struct member types are not inferred from construction sites; as above.
+        def bucket: () -> Bucket
+        # sig-gen gap: #1183 — as above.
+        def actual_count: () -> Integer
+        # sig-gen gap: #1183 — as above.
+        def status: () -> (:within | :over | :cleared | :reducible)
+        def delta: () -> Integer
+        # sig-gen gap: #1183 — as above.
+        def bucket=: (Bucket) -> Bucket
+        # sig-gen gap: #1183 — as above.
+        def actual_count=: (Integer) -> Integer
+        # sig-gen gap: #1183 — as above.
+        def status=: (:within | :over | :cleared | :reducible) -> (:within | :over | :cleared | :reducible)
+        # sig-gen gap: #1183 — as above.
+        def self.new: (?bucket: Bucket, ?actual_count: Integer, ?status: :within | :over | :cleared | :reducible) -> instance
+        # sig-gen gap: #1183 — as above.
+        def self.[]: (?bucket: Bucket, ?actual_count: Integer, ?status: :within | :over | :cleared | :reducible) -> instance
+      end
+
       # Load a baseline file from disk.
       # Returns `nil` when `path` is nil (no baseline configured).
       # Raises {LoadError} on malformed or unsupported content.
       def self.load: (::String? path, ?project_root: ::String) -> Baseline?
 
       # Build a baseline from a current run's diagnostic stream.
-      def self.from_diagnostics: (untyped diagnostics, ?match_mode: :rule | :message) -> Baseline
+      def self.from_diagnostics: (untyped diagnostics, ?match_mode: :rule | :message, ?project_root: ::String | ::Pathname) -> Baseline
 
-      attr_reader buckets: untyped
+      # Always an Array of Bucket — `initialize` freezes what it is given and every caller hands it
+      # Bucket instances (parse_row rows, from_diagnostics groups, `without`'s reject, or `[]`).
+      # sig-gen gap: #1154 — an `attr_reader` over an ivar assigned in `initialize` from a parameter
+      # is skipped (untyped return); the element type is hand-written.
+      attr_reader buckets: Array[Bucket]
 
-      def initialize: (untyped buckets) -> void
+      # `project_root` is `Pathname.new`'d, so a `Pathname` is accepted as well as a `String`
+      # (`without` re-passes the stored Pathname).
+      def initialize: (Array[Bucket] buckets, ?project_root: ::String | ::Pathname) -> void
 
       # Apply the baseline filter. Returns [surfaced_diagnostics, silenced_count].
-      def filter: (untyped diagnostics) -> [untyped, ::Integer]
+      # `diagnostics` stays `untyped`: `Analysis::Diagnostic`'s sig is partial (no `qualified_rule`),
+      # so a tighter param would put `diag.qualified_rule` behind an unsigned member. The declared
+      # `[Array[untyped], Integer]` diverges from sig-gen's inference
+      # (`[Array[untyped], untyped] | [untyped, 0]` — the literal seed and the accumulated local are
+      # unproven); the `Integer` count is the author's intent.
+      def filter: (untyped diagnostics) -> [Array[untyped], ::Integer]
 
-      # Report bucket-level drift for each recorded baseline bucket.
-      def audit: (untyped diagnostics) -> untyped
+      # Report bucket-level drift for each recorded baseline bucket — one DriftRow per bucket, in
+      # baseline-file order.
+      def audit: (untyped diagnostics) -> Array[DriftRow]
 
       # Return a new Baseline with the given buckets removed.
-      def without: (untyped buckets_to_drop) -> Baseline
+      def without: (Array[Bucket] buckets_to_drop) -> Baseline
 
       # Serialise to a YAML string.
       def to_yaml: () -> ::String

data/sig/rigor/analysis/fact_store.rbs

@@ -2,7 +2,7 @@ module Rigor
   module Analysis
     module CheckRules
       def self?.diagnose: (path: String, root: untyped, scope_index: Hash[untyped, Scope]) -> Array[Diagnostic]
-      def self?.build_node_collectors: (String path, untyped scope_index) -> Hash[Symbol, untyped]
+      def self?.build_node_collectors: (String path, untyped scope_index, ?untyped root) -> Hash[Symbol, untyped]
       def self?.node_collector_driver: (Hash[Symbol, untyped] collectors) -> untyped
       def self?.shadow_verify_converged_collectors: (String path, untyped root, untyped scope_index, Hash[Symbol, untyped]? collectors) -> void
       def self?.filter_suppressed: (Array[Diagnostic] diagnostics, comments: untyped, disabled_rules: Array[String]) -> Array[Diagnostic]