rigortype 0.2.7 → 0.2.8

data/lib/rigor/rbs_extended/conformance_checker.rb

@@ -5,48 +5,37 @@ require_relative "../inference/rbs_type_translator"
 
 module Rigor
   module RbsExtended
-    # Verifies every `rigor:v1:conforms-to <Interface>` class- /
-    # module-level directive in the loaded RBS environment (spec:
-    # `docs/type-specification/rbs-extended.md` § "Explicit
-    # conformance directive"). For each annotated class, the
-    # directive asserts the class satisfies the named structural
-    # interface as a *checked design assertion* — independent of
-    # whether any current call site exercises that requirement.
-    # Multiple directives on one class combine as an intersection:
-    # each interface is checked independently.
+    # Verifies every `rigor:v1:conforms-to <Interface>` class- / module-level directive in the loaded RBS
+    # environment (spec: `docs/type-specification/rbs-extended.md` § "Explicit conformance directive"). For each
+    # annotated class, the directive asserts the class satisfies the named structural interface as a *checked
+    # design assertion* — independent of whether any current call site exercises that requirement. Multiple
+    # directives on one class combine as an intersection: each interface is checked independently.
     #
     # ## Two checked tiers
     #
-    # 1. **Presence** (FP-free): an interface method the class provably does
-    #    NOT provide anywhere in its RBS-resolved method set (own, inherited,
-    #    included) is a definitive non-conformance.
-    # 2. **Signature compatibility** (covariant return / contravariant
-    #    params): for a method the class DOES provide, the provided RBS
-    #    signature must be a behavioural subtype of the interface's required
-    #    one. Both sides are *authored* RBS (the class in `signature_paths:`
-    #    RBS, the interface in a loaded `sig`/library), so this is the same
-    #    FP-safe both-sides-authored construction as the
-    #    [ADR-35](../../../docs/adr/35-override-signature-compatibility.md)
-    #    `def.override-*` rules — not the inferred-signature comparison whose
-    #    FP risk justified deferring it. Conservative: single-method-type
-    #    (non-overloaded) signatures only, `Dynamic[Top]` positions skipped,
-    #    fires only on a proven `accepts(...).no?` violation.
+    # 1. **Presence** (FP-free): an interface method the class provably does NOT provide anywhere in its
+    #    RBS-resolved method set (own, inherited, included) is a definitive non-conformance.
+    # 2. **Signature compatibility** (covariant return / contravariant params): for a method the class DOES
+    #    provide, the provided RBS signature must be a behavioural subtype of the interface's required one. Both
+    #    sides are *authored* RBS (the class in `signature_paths:` RBS, the interface in a loaded `sig`/library),
+    #    so this is the same FP-safe both-sides-authored construction as the
+    #    [ADR-35](../../../docs/adr/35-override-signature-compatibility.md) `def.override-*` rules — not the
+    #    inferred-signature comparison whose FP risk justified deferring it. Conservative: single-method-type
+    #    (non-overloaded) signatures only, `Dynamic[Top]` positions skipped, fires only on a proven
+    #    `accepts(...).no?` violation.
     #
     # ## Output records (all drained by {Rigor::Analysis::Runner})
     #
-    # - `Unsatisfied` — the class is missing one or more required interface
-    #   methods. Surfaces as `rbs_extended.unsatisfied-conformance`.
-    # - `IncompatibleSignature` — a provided method's signature violates the
-    #   interface contract (return widened, or a parameter narrowed). Same
-    #   rule, signature-specific message.
-    # - `UnresolvedInterface` — the named interface is not loaded (a typo, or
-    #   the defining library / `sig` set is not on the RBS load path).
-    #   Surfaces as `dynamic.rbs-extended.unresolved` `:info`, the fail-soft
-    #   channel the other directive parsers use, so a bad name never silently
-    #   disables the author's assertion.
+    # - `Unsatisfied` — the class is missing one or more required interface methods. Surfaces as
+    #   `rbs_extended.unsatisfied-conformance`.
+    # - `IncompatibleSignature` — a provided method's signature violates the interface contract (return widened,
+    #   or a parameter narrowed). Same rule, signature-specific message.
+    # - `UnresolvedInterface` — the named interface is not loaded (a typo, or the defining library / `sig` set is
+    #   not on the RBS load path). Surfaces as `dynamic.rbs-extended.unresolved` `:info`, the fail-soft channel
+    #   the other directive parsers use, so a bad name never silently disables the author's assertion.
     #
-    # Fail-soft throughout: a class whose own definition cannot be built (RBS
-    # error) is skipped rather than reported.
+    # Fail-soft throughout: a class whose own definition cannot be built (RBS error) is skipped rather than
+    # reported.
     module ConformanceChecker
       Unsatisfied = Data.define(:class_name, :interface_name, :missing_methods, :location)
       IncompatibleSignature = Data.define(:class_name, :interface_name, :method_name, :detail, :location)
@@ -113,14 +102,11 @@ module Rigor
         end
       end
 
-      # Returns a human-readable mismatch detail when `provided` is NOT a
-      # behavioural subtype of the `required` (interface) signature, else
-      # nil. Mirrors the ADR-35 override checks: covariant return,
-      # contravariant params, single method type only, `Dynamic[Top]`
-      # positions skipped (fires only on a proven `accepts(...).no?`).
-      # Also checks arity divergence and keyword-requiredness divergence
-      # (positional-type comparison only was the initial scope; these
-      # extend it to the cases that cause runtime ArgumentError).
+      # Returns a human-readable mismatch detail when `provided` is NOT a behavioural subtype of the `required`
+      # (interface) signature, else nil. Mirrors the ADR-35 override checks: covariant return, contravariant
+      # params, single method type only, `Dynamic[Top]` positions skipped (fires only on a proven
+      # `accepts(...).no?`). Also checks arity divergence and keyword-requiredness divergence (positional-type
+      # comparison only was the initial scope; these extend it to the cases that cause runtime ArgumentError).
       def signature_mismatch(required_method, provided_method)
         return nil unless required_method.method_types.size == 1
         return nil unless provided_method.method_types.size == 1
@@ -158,14 +144,13 @@ module Rigor
         nil
       end
 
-      # Checks positional-count divergence — cases that would cause a
-      # runtime `ArgumentError` even when every declared type matches.
-      # Skipped when either side has a rest parameter (`*args`) since
-      # that makes the arity range unbounded. Two violation shapes:
-      # (a) provided requires MORE positionals than the interface allows
-      #     (caller passes ≤ interface total → provided raises);
-      # (b) provided accepts FEWER positionals than the interface requires
-      #     (caller passes ≥ interface required → provided raises).
+      # Checks positional-count divergence — cases that would cause a runtime `ArgumentError` even when every
+      # declared type matches. Skipped when either side has a rest parameter (`*args`) since that makes the
+      # arity range unbounded. Two violation shapes:
+      # (a) provided requires MORE positionals than the interface allows (caller passes ≤ interface total →
+      #     provided raises);
+      # (b) provided accepts FEWER positionals than the interface requires (caller passes ≥ interface required →
+      #     provided raises).
       def arity_detail(required_method, provided_method)
         req_func = required_method.method_types.first.type
         prov_func = provided_method.method_types.first.type
@@ -193,11 +178,10 @@ module Rigor
       end
 
       # Checks keyword-requiredness divergence.
-      # (a) A keyword the interface requires that the provided method does
-      #     not accept at all → callers will pass it, provided will raise.
-      # (b) A keyword the provided method requires that the interface does
-      #     not mention → callers following the interface won't pass it,
-      #     provided will raise.
+      # (a) A keyword the interface requires that the provided method does not accept at all → callers will pass
+      #     it, provided will raise.
+      # (b) A keyword the provided method requires that the interface does not mention → callers following the
+      #     interface won't pass it, provided will raise.
       # Skipped when either side has a keyword rest (`**kwargs`).
       def keyword_detail(required_method, provided_method)
         req_func, prov_func = keyword_funcs(required_method, provided_method)
@@ -245,13 +229,11 @@ module Rigor
         (func.required_positionals + func.optional_positionals).map { |param| translate(param.type) }
       end
 
-      # Resolves the (possibly namespace-relative) `interface_name` against
-      # the declaring class's namespace chain, mirroring Ruby constant
-      # lookup: `conforms-to _Foo` inside `Bar::Baz` tries `Bar::Baz::_Foo`,
-      # `Bar::_Foo`, then top-level `_Foo` (longest prefix first). Returns
-      # the first interface definition that resolves, or nil. (A leading
-      # `::` is already stripped by the parser, so an intended-absolute name
-      # still resolves via the trailing top-level candidate.)
+      # Resolves the (possibly namespace-relative) `interface_name` against the declaring class's namespace
+      # chain, mirroring Ruby constant lookup: `conforms-to _Foo` inside `Bar::Baz` tries `Bar::Baz::_Foo`,
+      # `Bar::_Foo`, then top-level `_Foo` (longest prefix first). Returns the first interface definition that
+      # resolves, or nil. (A leading `::` is already stripped by the parser, so an intended-absolute name still
+      # resolves via the trailing top-level candidate.)
       def resolve_interface(rbs_loader, class_name, interface_name)
         candidate_interface_names(class_name, interface_name).each do |candidate|
           defn = rbs_loader.interface_definition(candidate)
@@ -265,11 +247,9 @@ module Rigor
         prefixes.map { |prefix| "#{prefix}::#{interface_name}" } + [interface_name]
       end
 
-      # Namespace prefixes of a qualified name, longest first:
-      # `"Bar::Baz"` → `["Bar::Baz", "Bar"]`. Covers both the
-      # `class Bar::Baz` and the `module Bar; class Baz` nesting shapes
-      # (a superset of `Module.nesting`, which the directive's resolved
-      # class name does not record).
+      # Namespace prefixes of a qualified name, longest first: `"Bar::Baz"` → `["Bar::Baz", "Bar"]`. Covers both
+      # the `class Bar::Baz` and the `module Bar; class Baz` nesting shapes (a superset of `Module.nesting`,
+      # which the directive's resolved class name does not record).
       def namespace_prefixes(class_name)
         parts = normalize(class_name).split("::")
         (1..parts.size).to_a.reverse.map { |count| parts.first(count).join("::") }

data/lib/rigor/rbs_extended/hkt_directives.rb

@@ -5,35 +5,25 @@ require_relative "../inference/hkt_body_parser"
 
 module Rigor
   module RbsExtended
-    # ADR-20 § "Decision D6" parser for the two new HKT
-    # directives that live in `.rbs` files at module / class
+    # ADR-20 § "Decision D6" parser for the two new HKT directives that live in `.rbs` files at module / class
     # scope:
     #
-    # - `%a{rigor:v1:hkt_register: uri=<uri> arity=<int>
-    #   variance=<v1>,<v2>,... bound=<class_name_or_untyped>}` —
-    #   registers a defunctionalised type-constructor URI
-    #   together with its arity, per-position variance, and
+    # - `%a{rigor:v1:hkt_register: uri=<uri> arity=<int> variance=<v1>,<v2>,... bound=<class_name_or_untyped>}` —
+    #   registers a defunctionalised type-constructor URI together with its arity, per-position variance, and
     #   erasure bound.
-    # - `%a{rigor:v1:hkt_define: uri=<uri> params=<P1>,<P2>,...
-    #   body=<body_text>}` — binds the URI to a type-function
-    #   body that {HktBodyParser} parses into an
-    #   {HktBody::Union} tree.
+    # - `%a{rigor:v1:hkt_define: uri=<uri> params=<P1>,<P2>,... body=<body_text>}` — binds the URI to a
+    #   type-function body that {HktBodyParser} parses into an {HktBody::Union} tree.
     #
     # ## Payload format
     #
-    # **Space-separated `key=value` pairs.** The format is
-    # constrained by RBS's `%a{...}` annotation grammar, which
-    # does NOT accept arbitrary nested punctuation (a JSON
-    # payload with quotes / nested braces will fail RBS
-    # parsing). Each value is a bare token: no quoting, no
-    # escaping. Values that contain spaces or `=` signs MUST
-    # be encoded via the `body=` key, which is special-cased
-    # to gobble everything from `body=` to the end of the
+    # **Space-separated `key=value` pairs.** The format is constrained by RBS's `%a{...}` annotation grammar,
+    # which does NOT accept arbitrary nested punctuation (a JSON payload with quotes / nested braces will fail RBS
+    # parsing). Each value is a bare token: no quoting, no escaping. Values that contain spaces or `=` signs MUST
+    # be encoded via the `body=` key, which is special-cased to gobble everything from `body=` to the end of the
     # payload — see `parse_define`.
     #
-    # Example annotations (write inside a class / module
-    # declaration so the annotation attaches to the decl
-    # RBS parses):
+    # Example annotations (write inside a class / module declaration so the annotation attaches to the decl RBS
+    # parses):
     #
     #   %a{rigor:v1:hkt_register: uri=json::value arity=1
     #     variance=out bound=untyped}
@@ -46,18 +36,13 @@ module Rigor
     #
     # ## Bound vocabulary
     #
-    # - `untyped` resolves to `Rigor::Type::Combinator.untyped`
-    #   (i.e. `Dynamic[Top]`, the ADR-20 WD2 default).
-    # - A bare class name (`String`, `Integer`, …) resolves
-    #   through `name_scope.nominal_for_name(...)` when
-    #   supplied, falling back to a raw `Rigor::Type::Nominal`
-    #   otherwise.
-    # - Anything else falls back to `untyped` and emits an
-    #   `:info` diagnostic via the supplied reporter (fail-soft
+    # - `untyped` resolves to `Rigor::Type::Combinator.untyped` (i.e. `Dynamic[Top]`, the ADR-20 WD2 default).
+    # - A bare class name (`String`, `Integer`, …) resolves through `name_scope.nominal_for_name(...)` when
+    #   supplied, falling back to a raw `Rigor::Type::Nominal` otherwise.
+    # - Anything else falls back to `untyped` and emits an `:info` diagnostic via the supplied reporter (fail-soft
     #   so an unrecognised bound never crashes the loader).
     #
-    # Richer bound forms (parameterised generics, unions,
-    # refinements) wait for a follow-up slice's expression
+    # Richer bound forms (parameterised generics, unions, refinements) wait for a follow-up slice's expression
     # parser.
     module HktDirectives
       module_function
@@ -68,10 +53,8 @@ module Rigor
       DEFAULT_VARIANCE = :inv
       DEFAULT_BOUND_LITERAL = "untyped"
 
-      # Parses one `%a{rigor:v1:hkt_register: ...}` payload
-      # string and returns a `Registration`, or `nil` when the
-      # string is not an hkt_register directive (so callers can
-      # walk a list of annotations without each having to
+      # Parses one `%a{rigor:v1:hkt_register: ...}` payload string and returns a `Registration`, or `nil` when the
+      # string is not an hkt_register directive (so callers can walk a list of annotations without each having to
       # pre-filter).
       def parse_register(string, name_scope: nil, reporter: nil, source_location: nil)
         payload = extract_payload(string, REGISTER_DIRECTIVE)
@@ -106,8 +89,7 @@ module Rigor
         nil
       end
 
-      # Parses one `%a{rigor:v1:hkt_define: ...}` payload
-      # string and returns a `Definition`, or `nil` when the
+      # Parses one `%a{rigor:v1:hkt_define: ...}` payload string and returns a `Definition`, or `nil` when the
       # string is not an hkt_define directive.
       def parse_define(string, reporter: nil, source_location: nil)
         payload = extract_payload(string, DEFINE_DIRECTIVE)
@@ -149,8 +131,7 @@ module Rigor
         return nil if idx.nil?
 
         payload = string[(idx + directive.size)..].to_s.strip
-        # Strip trailing `}` of the wrapping `%a{...}` form if
-        # the caller passed the raw annotation string. The
+        # Strip trailing `}` of the wrapping `%a{...}` form if the caller passed the raw annotation string. The
         # parser also accepts a pre-extracted payload.
         payload = payload.sub(/\}\z/, "") if payload.end_with?("}") && !balanced_braces?(payload)
         payload.empty? ? nil : payload
@@ -169,19 +150,15 @@ module Rigor
         depth.zero?
       end
 
-      # Parses a space-separated `key=value [key=value ...]`
-      # payload into a Hash. When `body_key` is supplied AND
-      # that key appears, everything from `<body_key>=` to
-      # the end of the payload becomes the value (body
-      # contents typically include spaces, `|`, `[]` etc.
-      # that the simple tokenizer cannot otherwise carry).
+      # Parses a space-separated `key=value [key=value ...]` payload into a Hash. When `body_key` is supplied AND
+      # that key appears, everything from `<body_key>=` to the end of the payload becomes the value (body
+      # contents typically include spaces, `|`, `[]` etc. that the simple tokenizer cannot otherwise carry).
       KV_KEY_PATTERN = /(?<![\w.])([a-z_]\w*)=/
       private_constant :KV_KEY_PATTERN
 
       def parse_kv_payload(payload, body_key:)
         result = {}
-        # Find every `<key>=` boundary; each value runs to
-        # the next boundary or end of string.
+        # Find every `<key>=` boundary; each value runs to the next boundary or end of string.
         markers = []
         payload.scan(KV_KEY_PATTERN) { markers << [::Regexp.last_match[1], ::Regexp.last_match.end(0)] }
         markers.each_with_index do |(key, value_start), i|
@@ -196,13 +173,10 @@ module Rigor
         result
       end
 
-      # ADR-20 slice 2b — parse the body String into an
-      # `HktBody::*` tree via {Inference::HktBodyParser.parse}.
-      # On parse failure: emit a fail-soft `:info` reporter
-      # entry and return `nil` so the resulting Definition
-      # keeps its `body` String slot but `body_tree` stays
-      # absent (the reducer falls back to `app.bound` at call
-      # time per ADR-20 D5).
+      # ADR-20 slice 2b — parse the body String into an `HktBody::*` tree via {Inference::HktBodyParser.parse}. On
+      # parse failure: emit a fail-soft `:info` reporter entry and return `nil` so the resulting Definition keeps
+      # its `body` String slot but `body_tree` stays absent (the reducer falls back to `app.bound` at call time
+      # per ADR-20 D5).
       def parse_body_tree(body, params, reporter:, source_location:)
         return nil if body.nil? || body.empty?
 

data/lib/rigor/rbs_extended/reporter.rb

@@ -2,35 +2,26 @@
 
 module Rigor
   module RbsExtended
-    # ADR-13 slice 3b — per-run accumulator for `RBS::Extended`
-    # diagnostic events that the parser / resolver cannot surface
-    # at the point of failure (the parsers are fail-soft, returning
-    # `nil` so call sites fall back to the RBS-declared type).
+    # ADR-13 slice 3b — per-run accumulator for `RBS::Extended` diagnostic events that the parser / resolver
+    # cannot surface at the point of failure (the parsers are fail-soft, returning `nil` so call sites fall back
+    # to the RBS-declared type).
     #
     # Owns two event streams:
     #
-    # - `#unresolved_payloads` — `rigor:v1:*` directive payloads
-    #   the resolver could not turn into a {Rigor::Type}. Surface
-    #   as `dynamic.rbs-extended.unresolved` `:info` diagnostics.
-    # - `#lossy_projections` — shape-projection type functions
-    #   (`pick_of` / `omit_of` / `partial_of` / `required_of` /
-    #   `readonly_of`) applied to a carrier that does not preserve
-    #   shape information (anything other than `Type::HashShape`
-    #   / `Type::Tuple`). Surface as
-    #   `dynamic.shape.lossy-projection` `:info` diagnostics.
+    # - `#unresolved_payloads` — `rigor:v1:*` directive payloads the resolver could not turn into a
+    #   {Rigor::Type}. Surface as `dynamic.rbs-extended.unresolved` `:info` diagnostics.
+    # - `#lossy_projections` — shape-projection type functions (`pick_of` / `omit_of` / `partial_of` /
+    #   `required_of` / `readonly_of`) applied to a carrier that does not preserve shape information (anything
+    #   other than `Type::HashShape` / `Type::Tuple`). Surface as `dynamic.shape.lossy-projection` `:info`
+    #   diagnostics.
     #
-    # Mutable through the run; consumed once by
-    # {Rigor::Analysis::Runner} at end-of-run. Each event is
-    # deduplicated by `(payload, source_location)` for unresolved
-    # and `(head, source_location)` for lossy-projection so a
-    # single annotation read from many call sites yields one
-    # diagnostic.
+    # Mutable through the run; consumed once by {Rigor::Analysis::Runner} at end-of-run. Each event is
+    # deduplicated by `(payload, source_location)` for unresolved and `(head, source_location)` for
+    # lossy-projection so a single annotation read from many call sites yields one diagnostic.
     #
-    # The reporter is intentionally thread-safe via a coarse
-    # `Mutex` because the inference engine may read the same
-    # method definition from multiple files in parallel; the
-    # critical sections are short (Array#include? + Array#<<) so
-    # the lock contention is negligible.
+    # The reporter is intentionally thread-safe via a coarse `Mutex` because the inference engine may read the
+    # same method definition from multiple files in parallel; the critical sections are short (Array#include? +
+    # Array#<<) so the lock contention is negligible.
     class Reporter
       UnresolvedEntry = Data.define(:payload, :source_location)
       LossyProjectionEntry = Data.define(:head, :source_location)
@@ -41,23 +32,19 @@ module Rigor
         @mutex = Mutex.new
       end
 
-      # @return [Array<UnresolvedEntry>] frozen snapshot of the
-      #   accumulated unresolved-payload events.
+      # @return [Array<UnresolvedEntry>] frozen snapshot of the accumulated unresolved-payload events.
       def unresolved_payloads
         @mutex.synchronize { @unresolved_payloads.dup.freeze }
       end
 
-      # @return [Array<LossyProjectionEntry>] frozen snapshot of
-      #   the accumulated lossy-projection events.
+      # @return [Array<LossyProjectionEntry>] frozen snapshot of the accumulated lossy-projection events.
       def lossy_projections
         @mutex.synchronize { @lossy_projections.dup.freeze }
       end
 
-      # Records a `dynamic.rbs-extended.unresolved` event. The
-      # `source_location` argument is the {RBS::Location} attached
-      # to the source annotation (or `nil` when the caller doesn't
-      # have one — the diagnostic falls back to a generic
-      # location in that case).
+      # Records a `dynamic.rbs-extended.unresolved` event. The `source_location` argument is the {RBS::Location}
+      # attached to the source annotation (or `nil` when the caller doesn't have one — the diagnostic falls back
+      # to a generic location in that case).
       def record_unresolved(payload:, source_location: nil)
         entry = UnresolvedEntry.new(payload: payload.to_s, source_location: source_location)
         @mutex.synchronize do
@@ -67,10 +54,8 @@ module Rigor
         end
       end
 
-      # Records a `dynamic.shape.lossy-projection` event for one
-      # of the five shape-projection heads. `head` MUST be a
-      # String (`"pick_of"`, `"omit_of"`, …); the diagnostic
-      # message identifies which projection degraded.
+      # Records a `dynamic.shape.lossy-projection` event for one of the five shape-projection heads. `head` MUST
+      # be a String (`"pick_of"`, `"omit_of"`, …); the diagnostic message identifies which projection degraded.
       def record_lossy_projection(head:, source_location: nil)
         entry = LossyProjectionEntry.new(head: head.to_s, source_location: source_location)
         @mutex.synchronize do
@@ -80,9 +65,8 @@ module Rigor
         end
       end
 
-      # True when no events have accumulated. Used by callers
-      # that want to skip the diagnostic-emission pass entirely
-      # on the common no-event path.
+      # True when no events have accumulated. Used by callers that want to skip the diagnostic-emission pass
+      # entirely on the common no-event path.
       def empty?
         @mutex.synchronize { @unresolved_payloads.empty? && @lossy_projections.empty? }
       end