rigortype 0.1.15 → 0.1.17

data/sig/rigor/plugin/manifest.rbs

@@ -3,7 +3,37 @@ class Rigor::Plugin::Manifest::Consumption
 end
 
 class Rigor::Plugin::Manifest
-  def initialize: (id: untyped, version: untyped, ?description: untyped, ?protocols: untyped, ?config_schema: untyped, ?produces: untyped, ?consumes: untyped, ?owns_receivers: untyped, ?type_node_resolvers: untyped, ?block_as_methods: untyped, ?heredoc_templates: untyped, ?trait_registries: untyped, ?external_files: untyped) -> void
+  def initialize: (id: untyped, version: untyped, ?description: untyped, ?config_schema: untyped, ?produces: untyped, ?consumes: untyped, ?owns_receivers: untyped, ?open_receivers: untyped, ?type_node_resolvers: untyped, ?block_as_methods: untyped, ?heredoc_templates: untyped, ?nested_class_templates: untyped, ?trait_registries: untyped, ?external_files: untyped, ?hkt_registrations: untyped, ?hkt_definitions: untyped, ?signature_paths: untyped, ?protocol_contracts: untyped, ?source_rbs_synthesizer: untyped, ?additional_initializers: untyped) -> void
+
+  # Public attribute readers (the full `attr_reader` surface). Plugins
+  # read `manifest.id` / `manifest.protocol_contracts` etc.; declaring
+  # them keeps the contract surface resolvable so ADR-43 ancestor
+  # resolution does not surface a false `call.undefined-method` on a
+  # real reader. Identity fields are typed; the structured slots stay
+  # `untyped` per the sparse `sig/` tree.
+  def id: () -> String
+  def version: () -> String
+  def description: () -> String?
+  def config_schema: () -> untyped
+  def config_defaults: () -> Hash[String, untyped]
+  def produces: () -> untyped
+  def consumes: () -> untyped
+  def owns_receivers: () -> untyped
+  def open_receivers: () -> untyped
+  def type_node_resolvers: () -> untyped
+  def block_as_methods: () -> untyped
+  def heredoc_templates: () -> untyped
+  def nested_class_templates: () -> untyped
+  def trait_registries: () -> untyped
+  def external_files: () -> untyped
+  def hkt_registrations: () -> untyped
+  def hkt_definitions: () -> untyped
+  def signature_paths: () -> untyped
+  def protocol_contracts: () -> untyped
+  def source_rbs_synthesizer: () -> untyped
+  def additional_initializers: () -> untyped
+
   def validate_config: (untyped) -> Array[String]
   def to_h: () -> Hash[String, untyped]
+  def hash: () -> Integer
 end

data/sig/rigor/rbs_extended.rbs

@@ -45,6 +45,8 @@ module Rigor
 
     def self?.read_flow_contribution: (untyped method_def) -> untyped?
 
+    def self?.parse_conforms_to_annotation: (String? string) -> String?
+
     class ParamOverride
       attr_reader param_name: Symbol
       attr_reader type: Type::t

data/sig/rigor/scope.rbs

@@ -19,6 +19,8 @@ module Rigor
     attr_reader discovered_method_visibilities: Hash[String, Hash[Symbol, Symbol]]
     attr_reader discovered_superclasses: Hash[String, String]
     attr_reader discovered_includes: Hash[String, Array[String]]
+    attr_reader discovered_class_sources: Hash[String, Set[String]]
+    attr_reader data_member_layouts: Hash[String, Array[Symbol]]
     attr_reader indexed_narrowings: Hash[IndexedKey, Type::t]
     attr_reader method_chain_narrowings: Hash[ChainKey, Type::t]
     attr_reader source_path: String?
@@ -66,8 +68,11 @@ module Rigor
     def discovered_method_visibility: (String | Symbol class_name, String | Symbol method_name) -> Symbol?
     def superclass_of: (String | Symbol class_name) -> String?
     def with_discovered_superclasses: (Hash[String, String] table) -> Scope
+    def data_member_layout: (String | Symbol class_name) -> Array[Symbol]?
+    def with_data_member_layouts: (Hash[String, Array[Symbol]] table) -> Scope
     def includes_of: (String | Symbol class_name) -> Array[String]
     def with_discovered_includes: (Hash[String, Array[String]] table) -> Scope
+    def with_discovered_class_sources: (Hash[String, Set[String]] table) -> Scope
     def indexed_narrowing: (Symbol receiver_kind, String | Symbol receiver_name, untyped key) -> Type::t?
     def with_indexed_narrowing: (Symbol receiver_kind, String | Symbol receiver_name, untyped key, Type::t type) -> Scope
     def without_indexed_narrowing: (Symbol receiver_kind, String | Symbol receiver_name, untyped key) -> Scope

data/sig/rigor/source.rbs

@@ -11,10 +11,22 @@ module Rigor
       def at_offset: (Integer offset) -> untyped?
     end
 
+    module Literals
+      def self?.symbol_or_string: (untyped? node) -> Symbol?
+      def self?.symbol_or_string_name: (untyped? node) -> String?
+      def self?.symbol: (untyped? node) -> Symbol?
+      def self?.symbol_name: (untyped? node) -> String?
+      def self?.symbol_arguments: (untyped? call_node) -> Array[Symbol]
+      def self?.symbol_arg: (untyped? call_node, Integer index) -> Symbol?
+    end
+
     module NodeWalker
       def self?.each: (untyped root) { (untyped) -> void } -> nil
                     | (untyped root) -> Enumerator[untyped, nil]
       def self?.walk: (untyped node) { (untyped) -> void } -> void
+      def self?.each_with_ancestors: (untyped root) { (untyped, Array[untyped]) -> void } -> nil
+                                   | (untyped root) -> Enumerator[untyped, nil]
+      def self?.walk_with_ancestors: (untyped node, Array[untyped] ancestors) { (untyped, Array[untyped]) -> void } -> void
     end
   end
 end

data/sig/rigor/type.rbs

@@ -1,9 +1,32 @@
 module Rigor
   module Type
-    type t = Top | Bot | Dynamic | Constant | IntegerRange | Nominal | Singleton | Union | Difference | Tuple | HashShape
+    type t = Top | Bot | Dynamic | Constant | IntegerRange | Nominal | Singleton | Union | Difference | Tuple | HashShape | DataClass | DataInstance
 
     type accepts_mode = :strict | :gradual | :loose
 
+    # The structural interface every `Type::*` carrier satisfies — the
+    # internal type-object API (see
+    # docs/internal-spec/internal-type-api.md). A structural *interface*
+    # (duck-typed: satisfied by having the methods, no `implements`
+    # clause), not a "protocol" — that word is reserved for ADR-28
+    # path-scoped protocol contracts. The closed `type t` union above is
+    # what the engine threads day-to-day; this records the shared
+    # per-carrier method contract in one place. Carriers supply the
+    # identity trio via `Rigor::ValueSemantics` and `accepts` via
+    # `Rigor::Type::AcceptanceRouter`.
+    interface _Type
+      def describe: (?Symbol verbosity) -> String
+      def erase_to_rbs: () -> String
+      def top: () -> Trinary
+      def bot: () -> Trinary
+      def dynamic: () -> Trinary
+      def accepts: (Type::t other, ?mode: accepts_mode) -> AcceptsResult
+      def ==: (untyped other) -> bool
+      def eql?: (untyped other) -> bool
+      def hash: () -> Integer
+      def inspect: () -> String
+    end
+
     class Top
       def self.instance: () -> Top
       def describe: (?Symbol verbosity) -> String
@@ -222,6 +245,38 @@ module Rigor
       def inspect: () -> String
     end
 
+    class DataClass
+      attr_reader members: Array[Symbol]
+      attr_reader class_name: String?
+      def initialize: (Array[Symbol] members, ?String? class_name) -> void
+      def describe: (?Symbol verbosity) -> String
+      def erase_to_rbs: () -> String
+      def top: () -> Trinary
+      def bot: () -> Trinary
+      def dynamic: () -> Trinary
+      def accepts: (Type::t other, ?mode: accepts_mode) -> AcceptsResult
+      def ==: (untyped other) -> bool
+      def hash: () -> Integer
+      def inspect: () -> String
+    end
+
+    class DataInstance
+      attr_reader members: Hash[Symbol, Type::t]
+      attr_reader class_name: String?
+      def initialize: (Hash[Symbol, Type::t] members, ?String? class_name) -> void
+      def member_names: () -> Array[Symbol]
+      def member_type: (Symbol name) -> Type::t?
+      def describe: (?Symbol verbosity) -> String
+      def erase_to_rbs: () -> String
+      def top: () -> Trinary
+      def bot: () -> Trinary
+      def dynamic: () -> Trinary
+      def accepts: (Type::t other, ?mode: accepts_mode) -> AcceptsResult
+      def ==: (untyped other) -> bool
+      def hash: () -> Integer
+      def inspect: () -> String
+    end
+
     class AcceptsResult
       attr_reader trinary: Trinary
       attr_reader mode: accepts_mode
@@ -282,6 +337,8 @@ module Rigor
       def self?.universal_int: () -> IntegerRange
       def self?.tuple_of: (*Type::t elements) -> Tuple
       def self?.hash_shape_of: (?Hash[untyped, Type::t]? pairs, **untyped options) -> HashShape
+      def self?.data_class_of: (members: Array[Symbol], ?class_name: String?) -> DataClass
+      def self?.data_instance_of: (members: Hash[Symbol, Type::t], ?class_name: String?) -> DataInstance
       def self?.union: (*Type::t types) -> Type::t
       def self?.key_of: (Type::t type) -> Type::t
       def self?.value_of: (Type::t type) -> Type::t

data/sig/rigor.rbs

@@ -53,6 +53,11 @@ module Rigor
       def error?: () -> bool
       def to_h: () -> Hash[String, untyped]
       def to_s: () -> String
+
+      # Singleton factories plugins build diagnostics through (the
+      # `node` / `location` are Prism values, received as `untyped`).
+      def self.from_node: (untyped node, path: String, message: String, ?severity: Symbol, ?rule: String?, ?source_family: String, ?receiver_type: untyped, ?method_name: untyped, ?project_definition_site: untyped) -> Rigor::Analysis::Diagnostic
+      def self.from_location: (untyped location, path: String, message: String, ?severity: Symbol, ?rule: String?, ?source_family: String, ?receiver_type: untyped, ?method_name: untyped, ?project_definition_site: untyped) -> Rigor::Analysis::Diagnostic
     end
 
     class Result
@@ -108,8 +113,13 @@ module Rigor
       attr_reader cache_store: untyped
       attr_reader plugin_registry: untyped
       attr_reader buffer: untyped
-      def initialize: (configuration: Configuration, ?explain: bool, ?cache_store: untyped, ?plugin_requirer: untyped, ?workers: Integer, ?collect_stats: bool, ?buffer: untyped, ?prebuilt: untyped, ?environment: untyped) -> void
+      attr_reader file_dependencies: Hash[String, untyped]
+      attr_reader analyzed_files: Array[String]
+      def initialize: (configuration: Configuration, ?explain: bool, ?cache_store: untyped, ?plugin_requirer: untyped, ?workers: Integer, ?collect_stats: bool, ?buffer: untyped, ?prebuilt: untyped, ?environment: untyped, ?record_dependencies: bool, ?analyze_only: untyped) -> void
       def run: (?Array[String] paths) -> Result
+      def run_source: (source: String, ?path: String) -> Result
+      def analysis_file_set: (?Array[String] paths) -> Array[String]
+      def file_dependents: () -> Hash[String, untyped]
       def prepare_project_scan: (?paths: Array[String]) -> untyped
     end
   end

data/skills/rigor-plugin-author/SKILL.md

@@ -90,20 +90,24 @@ Do NOT use this skill for:
 A Rigor plugin is a Ruby class that subclasses `Rigor::Plugin::Base`,
 declares a `manifest(id:, version:, …)`, and calls
 `Rigor::Plugin.register(self)` at load time. When `.rigor.yml` lists
-the plugin under `plugins:`, Rigor `require`s it and, for every
-analysed file, calls the plugin's `#diagnostics_for_file(path:,
-scope:, root:)` — handing it the file's Prism AST (`root`) and a
-`scope` it can query for inferred types. The plugin walks the AST and
-returns an array of `Rigor::Analysis::Diagnostic`. Optionally it also
-implements `#flow_contribution_for(call_node:, scope:)` to *supply* a
-return type for call sites the core analyzer types as `Dynamic`.
+the plugin under `plugins:`, Rigor `require`s it and runs its
+**node rules**: the plugin declares `node_rule(Prism::CallNode) { |node,
+scope, path, _fc, context| … }`, and the engine — which owns the single
+AST walk per file — hands every matching node to the block along with a
+`scope` it can query for inferred types. The block returns an array of
+`Rigor::Analysis::Diagnostic` (built via the `diagnostic` helper).
+Optionally the plugin also declares `dynamic_return(receivers:)` /
+`type_specifier(methods:)` to *supply* a return type or narrowing facts
+for call sites the core analyzer types as `Dynamic`. (The older
+`#diagnostics_for_file` / `#flow_contribution_for` fat hooks remain as
+deprecated escape valves — see Phase 2.)
 
 ## Phase outline
 
 | Phase | What | Reference |
 | --- | --- | --- |
 | 1 | Package and scaffold — gem vs project-private layout, gemspec / Gemfile, the plugin class skeleton, `.rigor.yml` activation. | [`references/01-plan-and-scaffold.md`](references/01-plan-and-scaffold.md) |
-| 2 | The walker — `diagnostics_for_file`, building `Diagnostic`s, querying `scope.type_of`, optional `flow_contribution_for`, RBS for the DSL. | [`references/02-walker-and-types.md`](references/02-walker-and-types.md) |
+| 2 | Node rules — `node_rule` (engine-owned walk), building `Diagnostic`s via `Base#diagnostic`, querying `scope.type_of`, calling the target library directly instead of reimplementing it (ADR-39: `Plugin::Inflector`, `Base.suggest`), optional `dynamic_return` / `type_specifier`, RBS for the DSL. | [`references/02-walker-and-types.md`](references/02-walker-and-types.md) |
 | 3 | Test and ship — fixture-based tests (RSpec / Minitest, no rigor internals), version pinning, README, publish or keep private. | [`references/03-test-and-ship.md`](references/03-test-and-ship.md) |
 
 ## Reading order — modules
@@ -111,5 +115,5 @@ return type for call sites the core analyzer types as `Dynamic`.
 | Module | Read | Covers |
 | --- | --- | --- |
 | 1 | [`references/01-plan-and-scaffold.md`](references/01-plan-and-scaffold.md) | **Phase 1.** The gem vs project-private packaging split, directory trees for both, gemspec template, project-private path-gem / `RUBYLIB` activation, the `Rigor::Plugin::Base` skeleton, `.rigor.yml` `plugins:` wiring. |
-| 2 | [`references/02-walker-and-types.md`](references/02-walker-and-types.md) | **Phase 2.** The `diagnostics_for_file` AST walk over Prism nodes, the `Diagnostic` constructor shape, asking the analyzer for inferred types via `scope.type_of`, the optional `flow_contribution_for` return-type hook, and shipping `sig/*.rbs` so the DSL's types are visible. |
+| 2 | [`references/02-walker-and-types.md`](references/02-walker-and-types.md) | **Phase 2.** The `node_rule` engine-owned AST walk over Prism nodes, the `Base#diagnostic` helper, asking the analyzer for inferred types via `scope.type_of`, two-pass / lexical context (`node_file_context` / `NodeContext`), the optional `dynamic_return` / `type_specifier` return-type hooks (and the deprecated `flow_contribution_for` escape valve), calling the target library's pure methods directly rather than reimplementing them (ADR-39: `Plugin::Inflector` over the real `ActiveSupport::Inflector`; `Base.suggest` for did-you-mean), and shipping `sig/*.rbs` so the DSL's types are visible. |
 | 3 | [`references/03-test-and-ship.md`](references/03-test-and-ship.md) | **Phase 3.** Testing a plugin from outside the monorepo — fixture projects driven through `rigor check --format json`, plus pure unit tests of dispatch tables — with RSpec or Minitest. Version pinning against the pre-1.0 contract. README. Publishing to RubyGems or keeping the plugin private. |

data/skills/rigor-plugin-author/references/01-plan-and-scaffold.md

@@ -184,10 +184,11 @@ module Rigor
         @module_name = config.fetch("module_name", "Default")
       end
 
-      # Called per analysed file. `root` is the file's Prism AST,
-      # `scope` answers inferred-type queries. Return an Array of
-      # Rigor::Analysis::Diagnostic. See 02-walker-and-types.md.
-      def diagnostics_for_file(path:, scope:, root:)
+      # The engine owns the AST walk and hands every matching node to
+      # this rule. `scope` answers inferred-type queries; return an
+      # Array of Rigor::Analysis::Diagnostic (built via `diagnostic`).
+      # See 02-walker-and-types.md.
+      node_rule Prism::CallNode do |node, scope, path, _file_context, _context|
         []
       end
     end
@@ -227,7 +228,7 @@ inert.
 
 ## Output of this module
 
-A scaffolded plugin that loads (even if `diagnostics_for_file` still
+A scaffolded plugin that loads (even if its `node_rule` still
 returns `[]`) and is activated in `.rigor.yml`. Proceed to Phase 2
 ([`02-walker-and-types.md`](02-walker-and-types.md)) to make it
 actually analyse.

data/skills/rigor-plugin-author/references/02-walker-and-types.md

@@ -1,57 +1,94 @@
-# 02 — The walker and types
+# 02 — Node rules and types
 
-Covers **Phase 2** — making `diagnostics_for_file` analyse the AST,
-emit diagnostics, and (optionally) contribute return types.
+Covers **Phase 2** — recognising the DSL's call shapes, emitting
+diagnostics, and (optionally) contributing return types. The engine
+owns the AST walk; you write the per-node check.
 
-## `diagnostics_for_file` — the core hook
+## `node_rule` — the core hook (ADR-37)
+
+A diagnostic-emitting plugin declares a **node rule**. The engine walks
+each analysed file's AST **once** and hands every node of the declared
+type to your block — so you write the check and never the traversal:
 
 ```ruby
-def diagnostics_for_file(path:, scope:, root:)
-  # root  — Prism::Node, the parsed file (a ProgramNode).
-  # scope — answers inferred-type queries: scope.type_of(node).
-  # path  — the file path, for Diagnostic#path.
-  # → return Array<Rigor::Analysis::Diagnostic>
+class MyPlugin < Rigor::Plugin::Base
+  manifest(id: "my-plugin", version: "0.1.0")
+
+  node_rule Prism::CallNode do |node, scope, path, file_context, context|
+    # node    — the Prism::CallNode the engine matched.
+    # scope   — answers inferred-type queries: scope.type_of(node).
+    # path    — the file path, for the diagnostic location.
+    # file_context — the value node_file_context built (see below); nil if none.
+    # context — Rigor::Plugin::NodeContext: lexical ancestors.
+    # → return Array<Rigor::Analysis::Diagnostic> ([] to fire nothing)
+  end
 end
 ```
 
-Walk `root` with a Prism visitor or a recursive descent, recognise
-the DSL's call shapes, and collect diagnostics. Keep the walk in a
-separate `Analyzer` class once it grows past a few methods — pass it
-`path` and let it return the diagnostic array.
+`node_rule(node_type)` matches by `node.is_a?(node_type)`, so declare
+the concrete class you care about (`Prism::CallNode` for almost every
+DSL plugin) or `Prism::Node` to see everything. The block runs through
+`instance_exec`, so `config`, `services`, `services.fact_store`, and the
+`diagnostic` helper (below) are all in scope. Declare multiple rules
+(they run in declaration order); a plugin that declares none pays zero
+cost. Keep the matching logic in a separate `Analyzer` class once it
+grows — have it take the call node and return location-free `Violation`
+rows the rule positions with `diagnostic` (the bundled plugins follow
+this `Analyzer.violations_for` split, which also makes the logic
+unit-testable without running the whole engine).
+
+> The legacy `diagnostics_for_file(path:, scope:, root:)` hook — where
+> you hand-rolled a `def walk` / `compact_child_nodes.each` recursion
+> over `root` yourself — is the **deprecated whole-file escape valve**.
+> Use it only for a genuinely file-scoped result (a single load-error
+> row, or a check that needs the whole parsed file at once). New
+> node-scoped checks use `node_rule`.
 
 ### Recognising call sites
 
-Most DSL plugins key off `Prism::CallNode`:
-
-```ruby
-def each_call(node, &block)
-  block.call(node) if node.is_a?(Prism::CallNode)
-  node&.compact_child_nodes&.each { |child| each_call(child, &block) }
-end
-```
-
-Then match on `node.name` (the method name, a Symbol),
-`node.receiver`, and `node.arguments&.arguments`.
+Inside the rule, match on `node.name` (the method name, a Symbol),
+`node.receiver` (nil for an implicit-self call), and
+`node.arguments&.arguments`. For literal `:sym` / `"str"` arguments
+reach for `Rigor::Source::Literals` (`symbol_or_string(node)` /
+`symbol_arguments(call)` / `symbol_arg(call, i)`) rather than
+re-deriving the `unescaped.to_sym` shape.
+
+### Two-pass and lexical context
+
+- **Same-file collect-then-validate** (gather declared names, then
+  validate references): declare `node_file_context { |root, scope| … }`.
+  It runs once per file before the walk and its return value is threaded
+  to every rule as `file_context`. (A *cross-file* collect belongs in
+  `#prepare` + `services.fact_store` instead — see
+  [`01-plan-and-scaffold.md`](01-plan-and-scaffold.md).)
+- **Where the node sits**: `context` (a `Rigor::Plugin::NodeContext`)
+  carries the lexical ancestor chain — `context.enclosing_def`,
+  `context.enclosing_module`, `context.enclosing_block(:describe)`, and
+  the raw `context.ancestors`. Read it when the check depends on the
+  enclosing class / method / block DSL (the enclosing controller a
+  `before_action` sits in, the `describe <Model>` a matcher is under).
 
 ## Building a `Diagnostic`
 
-Every diagnostic the plugin emits is a `Rigor::Analysis::Diagnostic`.
-A small constructor helper keeps the call sites clean:
+Use the `Base#diagnostic` helper — it internalises the load-bearing
+1-based `line` / `start_column + 1` convention so you never unpack
+`node.location` by hand:
 
 ```ruby
-def diagnostic(path, node, severity:, rule:, message:)
-  loc = node.location
-  Rigor::Analysis::Diagnostic.new(
-    path:     path,
-    line:     loc.start_line,
-    column:   loc.start_column + 1,   # 1-based column
-    message:  message,
-    severity: severity,               # :error | :warning | :info
-    rule:     rule                    # short kebab-case id
-  )
+node_rule Prism::CallNode do |node, scope, path, _fc, _ctx|
+  next [] unless offending?(node)
+
+  [diagnostic(node, path: path, message: "...", severity: :error, rule: "my-rule")]
 end
 ```
 
+Pass `location:` (a Prism location) to point at a sub-location rather
+than the whole node — typically `location: node.message_loc`, so a
+method-name diagnostic points at the name, not the receiver-spanning
+whole call. Do **not** set `source_family` — the runner stamps
+`plugin.<manifest.id>` on every returned diagnostic, so anything you set
+is overwritten.
+
 `rule` is a short identifier (`dimension-mismatch`,
 `unknown-state`). Rigor namespaces it under your plugin —
 diagnostics surface as `plugin.<manifest.id>.<rule>`, and that
@@ -87,46 +124,80 @@ Match with `case`/`when` on the carrier class. Treat any carrier you
 do not recognise as "decline to act" — never crash on an unexpected
 type.
 
-## Optional — contribute a return type with `flow_contribution_for`
+## Use the target library, don't reimplement it (ADR-39)
+
+A plugin may **call the pure methods of the library it targets
+directly** instead of reimplementing them — the Ruby analogue of a
+PHPStan extension calling into the real framework. Reimplementing a
+library's rules (an inflector, a status-code table, …) risks diverging
+from the real behaviour, and a wrong *derived* fact (a wrong class /
+helper / column name) is a false positive on working code. So declare
+the target gem as your plugin's dependency and call its safe methods.
 
-> **Critical — this hook does NOT make a method "defined", so it does
+The bundled `Rigor::Plugin::Inflector` is the worked example — it calls
+the real `ActiveSupport::Inflector` rather than a hand-rolled
+approximation. If your plugin needs inflection, use it:
+
+```ruby
+Rigor::Plugin::Inflector.classify("users")     # => "User"
+Rigor::Plugin::Inflector.tableize("BlogPost")  # => "blog_posts"
+```
+
+For your own target library, follow the same harness: a **fixed
+allow-list** of pure methods, inputs derived from source, and **decline
+(return nil / emit nothing) when the library is unavailable — never
+approximate**. How the call is isolated from Rigor (in-process, a forked
+worker, or a `Ruby::Box`) is a configurable strategy the user picks
+(`plugins_isolation:`); you just call the method.
+
+For the common "did you mean …?" suggestion, use the shared helper
+rather than hand-rolling Levenshtein:
+
+```ruby
+Rigor::Plugin::Base.suggest(typo, known_names)  # nearest match, or nil
+```
+
+## Optional — contribute a return type with `dynamic_return` / `type_specifier`
+
+> **Critical — these hooks do NOT make a method "defined", so they do
 > NOT suppress `call.undefined-method`.** Method *existence* and call
-> *type* are two independent checks. `flow_contribution_for` sharpens
+> *type* are two independent checks. A return-type contribution sharpens
 > the type of a call the analyzer has **already resolved to a real
 > method** (turning a `Dynamic` return into something precise). It is
 > never consulted for a receiver/method the analyzer cannot find — that
-> fires `call.undefined-method` first, and a flow contribution does
-> nothing to silence it. **If your goal is to kill a
-> `call.undefined-method` cluster on a DSL-generated method (the common
-> reason `rigor-project-init` hands off to this skill), the fix is to
-> make the method *exist* in Rigor's view — ship RBS declaring it (see
-> "Shipping RBS for the DSL" below), not a flow contribution.** Reach
-> for `flow_contribution_for` only when the call already resolves and
-> you want a *better return type*.
+> fires `call.undefined-method` first, and a contribution does nothing
+> to silence it. **If your goal is to kill a `call.undefined-method`
+> cluster on a DSL-generated method (the common reason
+> `rigor-project-init` hands off to this skill), the fix is to make the
+> method *exist* in Rigor's view — ship RBS declaring it (see "Shipping
+> RBS for the DSL" below), not a return-type contribution.** Reach for
+> these only when the call already resolves and you want a *better
+> return type*.
 
 A plugin can do more than emit diagnostics: it can *supply* the
-inferred return type for a call site the core analyzer would
-otherwise type as `Dynamic`. Implement `flow_contribution_for`:
+inferred return type (or narrowing facts) for a call site the core
+analyzer would otherwise type as `Dynamic`. ADR-37 gives two narrow,
+declaratively-gated DSLs — prefer them; the engine indexes plugins by
+their gate so it only calls the block for matching calls:
 
 ```ruby
-def flow_contribution_for(call_node:, scope:)
-  return nil unless call_node.is_a?(Prism::CallNode)
-  # ... decide the call site's real return type ...
-  return nil if undecidable   # nil = "I have nothing to add"
-
-  Rigor::FlowContribution.new(
-    return_type: a_rigor_type,
-    provenance: Rigor::FlowContribution::Provenance.new(
-      source_family: "plugin.#{manifest.id}",
-      plugin_id:     manifest.id,
-      node:          call_node,
-      descriptor:    nil
-    )
-  )
+# Per-call-site RETURN TYPE, gated on the receiver's class.
+# The block fires only when the receiver type's class is (or inherits
+# from) a declared `receivers:` entry. Return a Rigor::Type or nil.
+dynamic_return receivers: ["Money"] do |call_node, scope|
+  next nil unless call_node.name == :+
+  Rigor::Type::Combinator.nominal_of("Money")
+end
+
+# Post-return NARROWING FACTS, gated on the call's method name.
+# Return an Array of facts (or nil). Used for assertion / predicate
+# narrowing (`assert_kind_of(Foo, x)` ⇒ x is Foo afterwards).
+type_specifier methods: [:assert_kind_of] do |call_node, scope|
+  # ... build and return the post-return facts ...
 end
 ```
 
-Build the `return_type` with `Rigor::Type::Combinator`:
+Build return types with `Rigor::Type::Combinator`:
 
 ```ruby
 Rigor::Type::Combinator.nominal_of("Money")        # a class type
@@ -134,14 +205,27 @@ Rigor::Type::Combinator.constant_of(true)          # a literal
 Rigor::Type::Combinator.union(a, b)                # a union
 ```
 
-Returning `nil` is always safe — it means "no contribution", and the
-core analyzer keeps its own answer. Contribute a type only when the
+Returning `nil` (or `[]`) is always safe — it means "no contribution",
+and the core analyzer keeps its own answer. Contribute only when the
 plugin is confident; a wrong contribution propagates downstream.
 
-This hook is the most contract-sensitive surface — it is the part
-most likely to shift before v0.2.0. Implement it only if the plugin
-genuinely needs to sharpen call-site types; a diagnostics-only
-plugin can skip it entirely.
+`receivers:` / `methods:` are the greppable gates the
+`rigor plugins --capabilities` catalogue enumerates — run it to see
+exactly what each loaded plugin contributes.
+
+> **The deprecated escape valve.** The original fat hook,
+> `flow_contribution_for(call_node:, scope:)`, returns a single
+> `Rigor::FlowContribution` and is still consulted alongside the narrow
+> DSLs. It is retained only for the two shapes the narrow DSLs do not
+> express: a **method-gated return type** (an RSpec `let(:x) { … }`
+> binding, a Sorbet `sig`-driven return — keyed on the method, not a
+> fixed receiver class) and a **dynamic per-project receiver set**
+> (ActiveStorage's `Attached::One` on discovered model classes). If your
+> plugin needs one of those, use `flow_contribution_for`; otherwise
+> prefer `dynamic_return` / `type_specifier`. These return-type surfaces
+> are the most contract-sensitive part of the API — implement one only
+> if the plugin genuinely needs to sharpen call-site types; a
+> diagnostics-only plugin skips them entirely.
 
 ## Shipping RBS for the DSL — the way to suppress `call.undefined-method`
 
@@ -151,7 +235,7 @@ If the DSL introduces methods or classes that Rigor cannot see (a
 Rigor RBS declaring them so *core* inference — not just your plugin —
 treats them as **defined**. This is what removes the
 `call.undefined-method` diagnostics on those methods; nothing else
-(not `diagnostics_for_file`, not `flow_contribution_for`) makes a
+(not a `node_rule`, not `dynamic_return` / `type_specifier`) makes a
 method exist in Rigor's view.
 
 Two ways to wire the RBS, depending on how the plugin is packaged:
@@ -197,8 +281,8 @@ They compose — many plugins ship both.
 
 ## Output of this module
 
-A plugin whose `diagnostics_for_file` recognises the DSL and emits
-diagnostics with correct severities and rule ids — optionally a
-`flow_contribution_for` and a `sig/` bundle. Verify by eye with
-`rigor check`; lock it down with tests in Phase 3
+A plugin whose `node_rule`(s) recognise the DSL and emit diagnostics
+with correct severities and rule ids — optionally a `dynamic_return` /
+`type_specifier` and a `sig/` bundle. Verify by eye with `rigor check`;
+lock it down with tests in Phase 3
 ([`03-test-and-ship.md`](03-test-and-ship.md)).

data/skills/rigor-plugin-author/references/03-test-and-ship.md

@@ -114,9 +114,9 @@ SKILL.md). Concretely:
 - Your plugin's own version is normal semver, independent of
   `rigortype`'s.
 - When you bump the `rigortype` pin to a new minor, **re-run the
-  full test suite** — the walker hook signature or the `Diagnostic` /
-  type-carrier shapes may have changed. The fixture CLI tests are
-  what catch a contract drift.
+  full test suite** — the `node_rule` / contribution hook signatures
+  or the `Diagnostic` / type-carrier shapes may have changed. The
+  fixture CLI tests are what catch a contract drift.
 - State the supported `rigortype` range in the README so users do
   not pair the plugin with an incompatible Rigor.