rigortype 0.1.19 → 0.2.0

data/lib/rigor/inference/struct_fold_safety.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "../source/constant_path"
+
+module Rigor
+  module Inference
+    # ADR-48 Struct follow-up, slice 3 — the fold-safe-local scan. Determines,
+    # for a single local-variable scope (a method body or the program
+    # top-level), which `Struct`-materialised locals are **provably never
+    # mutated, aliased, or escaped** and so may have their member reads folded
+    # off a *stored* binding (relaxing the slice-2 fresh-receiver gate).
+    #
+    # The analysis is a conservative ALLOW-LIST, not a deny-list: a local is
+    # fold-safe only when *every* read of it is the receiver of a known-pure
+    # read call. Anything the scan does not recognise as a pure read — a
+    # setter, an `[]=` / operator-write, an argument / alias / container store
+    # / return (escape), or an unknown method call (which could mutate `self`
+    # internally) — disqualifies the local. A missed case therefore makes the
+    # scan over-conservative (no fold), **never unsound** (folding a mutated
+    # value) — the false-positive-safe direction.
+    #
+    # Soundness rests on a counting identity: a local `n` is fold-safe iff
+    # *every* `LocalVariableReadNode(n)` is the receiver of a pure-read call.
+    # Equivalently `total_reads(n) == pure_receiver_reads(n)`. Any other
+    # occurrence — `n` as a setter receiver (`n.x = v` is a `:x=` call, not a
+    # pure read), an `[]=`/operator-write receiver (the receiver read is not
+    # under a pure call), a call argument, an assignment RHS (alias), a
+    # container element, a bare value (return/escape) — leaves a read that is
+    # not a pure-receiver read, so the counts diverge.
+    #
+    # See docs/notes/20260615-struct-folding-slice3-design.md and
+    # docs/adr/48-data-struct-value-folding.md § "Struct follow-up".
+    module StructFoldSafety
+      module_function
+
+      EMPTY = Set.new.freeze
+
+      # The fixed `Struct` read methods that never mutate. A member-reader name
+      # (`:x`) is added per-local from the local's recorded layout. A setter
+      # (`:x=`), `:[]=`, `store`, `push`, etc. are deliberately absent.
+      FIXED_READS = %i[
+        [] dig to_h to_hash to_a values members deconstruct deconstruct_keys
+        == != eql? equal? hash inspect to_s size length frozen? each each_pair
+        values_at with
+      ].to_set.freeze
+
+      # Nested `def` / `class` / `module` bodies open a *new* local-variable
+      # scope, so the scan does not descend into them — a local of the same
+      # name there is a different binding. Blocks share the enclosing locals
+      # (closures), so the scan does descend into them.
+      def scope_boundary?(node)
+        node.is_a?(Prism::DefNode) || node.is_a?(Prism::ClassNode) ||
+          node.is_a?(Prism::ModuleNode) || node.is_a?(Prism::SingletonClassNode)
+      end
+
+      # @param root [Prism::Node, nil] the local-variable scope to scan.
+      # @param layout_lookup [#call] a `String -> Array[Symbol] | nil` resolver
+      #   mapping a constant receiver name to its struct member list.
+      # @return [Set<Symbol>] the fold-safe local names.
+      def fold_safe_locals(root, layout_lookup)
+        return EMPTY if root.nil?
+
+        members = {}
+        writes = Hash.new(0)
+        collect_struct_locals(root, layout_lookup, members, writes)
+        return EMPTY if members.empty?
+
+        total = Hash.new(0)
+        pure = Hash.new(0)
+        count_uses(root, members, total, pure)
+
+        safe = members.each_key.select do |name|
+          writes[name] == 1 && total[name].positive? && total[name] == pure[name]
+        end
+        safe.empty? ? EMPTY : safe.to_set
+      end
+
+      # Pass 1 — record each local's single struct materialisation (its member
+      # set) and count its assignments. A local assigned more than once is
+      # later excluded (the static fold-safe set cannot track a rebinding).
+      def collect_struct_locals(node, layout_lookup, members, writes)
+        return if node.nil?
+
+        if node.is_a?(Prism::LocalVariableWriteNode)
+          writes[node.name] += 1
+          found = struct_materialization_members(node.value, layout_lookup)
+          members[node.name] = found if found
+        end
+
+        each_local_scope_child(node) do |child|
+          collect_struct_locals(child, layout_lookup, members, writes)
+        end
+      end
+
+      # Pass 2 — count, per recorded struct local, total reads vs. reads that
+      # are the receiver of a pure-read call.
+      def count_uses(node, members, total, pure)
+        return if node.nil?
+
+        total[node.name] += 1 if node.is_a?(Prism::LocalVariableReadNode) && members.key?(node.name)
+
+        if node.is_a?(Prism::CallNode)
+          receiver = node.receiver
+          if receiver.is_a?(Prism::LocalVariableReadNode) && members.key?(receiver.name) &&
+             pure_read_call?(node, members[receiver.name])
+            pure[receiver.name] += 1
+          end
+        end
+
+        each_local_scope_child(node) do |child|
+          count_uses(child, members, total, pure)
+        end
+      end
+
+      # A call is a pure read of the receiver when its name is a fixed Struct
+      # read or one of the receiver's member readers. Setters (`:x=`), `:[]=`,
+      # and any unknown method are excluded.
+      def pure_read_call?(call_node, member_set)
+        name = call_node.name
+        FIXED_READS.include?(name) || member_set.include?(name)
+      end
+
+      # The member set of a `<Struct chain>.new(...)` / `.[]` materialisation,
+      # or nil. Handles the inline `Struct.new(:a, :b).new(...)` form and the
+      # `Const.new(...)` form (resolved through the layout side-table).
+      def struct_materialization_members(value_node, layout_lookup)
+        return nil unless value_node.is_a?(Prism::CallNode)
+        return nil unless %i[new []].include?(value_node.name)
+
+        receiver = value_node.receiver
+        case receiver
+        when Prism::CallNode
+          struct_new_member_set(receiver)
+
+        when Prism::ConstantReadNode, Prism::ConstantPathNode
+          name = Source::ConstantPath.qualified_name_or_nil(receiver)
+          name && member_set_of(layout_lookup.call(name))
+        end
+      end
+
+      # The Symbol member set of a literal `Struct.new(:a, :b [, keyword_init:])`
+      # call, or nil. (A leading String name and the trailing options hash are
+      # ignored — only the literal-Symbol positionals contribute.)
+      def struct_new_member_set(call_node)
+        return nil unless call_node.is_a?(Prism::CallNode) && call_node.name == :new
+        return nil unless meta_constant?(call_node.receiver, :Struct)
+
+        args = call_node.arguments&.arguments || []
+        positional = args.last.is_a?(Prism::KeywordHashNode) ? args[0..-2] : args
+        positional = positional[1..] if positional.first.is_a?(Prism::StringNode)
+        return nil if positional.nil? || positional.empty?
+        return nil unless positional.all?(Prism::SymbolNode)
+
+        positional.to_set { |sym| sym.unescaped.to_sym }
+      end
+
+      def member_set_of(members)
+        members && !members.empty? ? members.to_set : nil
+      end
+
+      def meta_constant?(node, name)
+        case node
+        when Prism::ConstantReadNode then node.name == name
+        when Prism::ConstantPathNode then node.parent.nil? && node.name == name
+        end
+      end
+
+      # Yields each child to recurse into, skipping the subtree of a nested
+      # local-variable-scope boundary (a `def` / `class` / `module`).
+      def each_local_scope_child(node)
+        node.compact_child_nodes.each do |child|
+          next if scope_boundary?(child)
+
+          yield child
+        end
+      end
+    end
+  end
+end

data/lib/rigor/inference/synthetic_method.rb

@@ -8,13 +8,13 @@ module Rigor
     # the template name. Stored in {SyntheticMethodIndex} and
     # consulted by {MethodDispatcher} below the RBS dispatch tier.
     #
-    # Per ADR-16 § WD13 (cost-bounded best-effort): the v0.1.x
-    # delivery commitment is the floor — method names emit; their
-    # return types degrade to `Dynamic[T]` until slice 6
-    # (precision promotion) routes the recorded `return_type`
-    # string through ADR-13's `Plugin::TypeNodeResolver` chain.
-    # The string is preserved so the ceiling slice can resolve it
-    # without re-walking.
+    # Per ADR-16 § WD13 (cost-bounded best-effort): method names
+    # emit with return types promoted by the dispatcher's Slice 6
+    # tiers — Slice 6a promotes via `origin_module` (TierB) and
+    # Slice 6b via `return_type` nominal lookup (TierC). The
+    # `return_type` string is preserved so promotion can resolve
+    # it without re-walking; `"untyped"` / `"void"` placeholders
+    # fall back to `Dynamic[Top]`.
     #
     # The `provenance` Hash carries debug / `--explain` metadata:
     # plugin id, the template's call shape, and the source

data/lib/rigor/language_server/completion_provider.rb

@@ -21,20 +21,14 @@ require_relative "../type/hash_shape"
 
 module Rigor
   module LanguageServer
-    # Answers `textDocument/completion` requests. v1 (slice 5)
-    # ships method completion for `obj.|`: when the cursor sits on
-    # a `CallNode` with a known-type receiver, the provider
-    # enumerates the receiver's RBS-known methods and returns each
-    # as an LSP `CompletionItem`.
-    #
-    # Constant-path completion (slice 6), Union / Intersection /
-    # Refined / Shape receiver handling (slice 7), and parse-recovery
-    # fallback for malformed buffers (slice 8) extend this v1 floor.
+    # Answers `textDocument/completion` requests. Provides method
+    # completion for `obj.|` (known-type receiver → RBS-known methods),
+    # constant-path completion, hash-key completion, Union / Intersection /
+    # Refined / Shape receiver handling, and parse-recovery fallback for
+    # malformed buffers (sentinel injection).
     #
     # LSP `CompletionItemKind` values used:
-    # - 2 = Method
-    #
-    # Slice 6 will add 7 (Class), 9 (Module), 21 (Constant).
+    # - 2 = Method, 5 = Field, 7 = Class, 9 = Module, 21 = Constant.
     class CompletionProvider # rubocop:disable Metrics/ClassLength
       include BufferResolution
 

data/lib/rigor/language_server/diagnostic_publisher.rb

@@ -15,10 +15,10 @@ module Rigor
     # a `BufferBinding` from the BufferTable entry, runs the Runner,
     # and pushes the resulting LSP `Diagnostic[]` through the writer.
     #
-    # Slice 4 is synchronous: each call blocks until analysis
-    # completes (typically 100-300ms warm). Debouncing (200ms
-    # quiet-time before publish) and Ractor-pool dispatch are
-    # queued for slice 4b / slice 8 respectively.
+    # Debouncing is wired via an optional `Debouncer` injected at
+    # construction (delay defaults to 200ms quiet-time); without a
+    # debouncer each call blocks synchronously (primarily for specs).
+    # Ractor-pool dispatch is queued.
     class DiagnosticPublisher
       # Maps Rigor severity symbols to LSP DiagnosticSeverity
       # integers per spec § "Diagnostic":

data/lib/rigor/language_server/document_symbol_provider.rb

@@ -128,9 +128,9 @@ module Rigor
       end
 
       # LSP `Range` is 0-based start + end with `character` in
-      # UTF-16 code units. Slice 6 emits byte columns (correct for
-      # ASCII source); UTF-16 conversion stays queued per design
-      # doc § "Open questions".
+      # UTF-16 code units. This implementation emits byte columns
+      # (correct for ASCII source); UTF-16 conversion stays queued
+      # per design doc § "Open questions".
       def range_from(location)
         {
           start: { line: location.start_line - 1, character: location.start_column },

data/lib/rigor/language_server/hover_provider.rb

@@ -64,9 +64,8 @@ module Rigor
       end
 
       def base_scope(_path)
-        # Slice 7: pull the Environment from the cached
-        # ProjectContext so hovers don't pay the RBS-load tax on
-        # every cursor stop.
+        # Pulls the Environment from the cached ProjectContext so
+        # each hover avoids repeating the RBS-load build.
         Scope.empty(environment: @project_context.environment)
       end
     end

data/lib/rigor/language_server/hover_renderer.rb

@@ -11,17 +11,8 @@ module Rigor
   module LanguageServer
     # Builds the LSP `Hover.contents` markdown body. Dispatches on
     # the hovered Prism node class so each shape (method call,
-    # constant, local, literal, …) gets the most relevant
-    # type-aware presentation.
-    #
-    # Slice A1 (this commit) ships:
-    # - default body bit-for-bit matching the LSP v1 slice 5
-    #   output (`type:` / `erased:` / `node:`),
-    # - `Prism::CallNode` specialisation surfacing the receiver
-    #   type + RBS-erased method signature.
-    #
-    # Slices A2-A4 extend the dispatch with constant /
-    # local / ivar / literal renderers per
+    # constant, local, ivar, literal) gets the most relevant
+    # type-aware presentation per
     # `docs/design/20260517-lsp-hover-completion.md`.
     class HoverRenderer
       # @param node_scope_lookup [#[]] node-to-scope table built

data/lib/rigor/language_server/server.rb

@@ -6,21 +6,13 @@ require_relative "buffer_table"
 module Rigor
   module LanguageServer
     # LSP server lifecycle state machine + JSON-RPC method dispatcher.
-    #
-    # Slice 1 (this commit) ships:
-    # - State machine: `:uninitialized` → `:initialized` → `:shutdown`
-    #   → `:exited`.
-    # - Three lifecycle handlers: `initialize`, `shutdown`, `exit`.
-    # - {#dispatch} which routes (method, params) to the matching
-    #   handler and returns the response payload (or `nil` for
-    #   notifications). Out-of-state requests return the
-    #   spec-defined `InvalidRequest` (-32002) / `MethodNotFound`
-    #   (-32601) error shapes.
-    #
-    # Slice 2 wraps this dispatcher in a stdio JSON-RPC reader /
-    # writer so the CLI subcommand can serve real LSP clients.
-    # Slice 3+ adds document sync; slice 4+ adds publishDiagnostics;
-    # slice 5-8 add the rest of the v1 capability surface.
+    # State machine: `:uninitialized` → `:initialized` → `:shutdown`
+    # → `:exited`. {#dispatch} routes (method, params) to the matching
+    # handler and returns the response payload (`nil` for notifications);
+    # out-of-state requests return `InvalidRequest` (-32002) /
+    # `MethodNotFound` (-32601). Full v1 capability surface (document
+    # sync, publishDiagnostics, hover, completion, sig-help, folding,
+    # selection, and watched-file invalidation) is implemented.
     class Server # rubocop:disable Metrics/ClassLength
       # JSON-RPC error codes per LSP spec § "Response Message".
       ERROR_PARSE_ERROR      = -32_700
@@ -58,8 +50,8 @@ module Rigor
       #   the providers read on every request. When present,
       #   `workspace/didChangeWatchedFiles` and
       #   `workspace/didChangeConfiguration` invalidate the cache;
-      #   nil means "no project context", which is the slice 1-6
-      #   behaviour (each request rebuilds env from scratch).
+      #   nil means "no project context": each request rebuilds env
+      #   from scratch (mainly for specs and backward compatibility).
       def initialize(buffer_table: BufferTable.new, publisher: nil, # rubocop:disable Metrics/ParameterLists
                      hover_provider: nil, document_symbol_provider: nil,
                      completion_provider: nil, signature_help_provider: nil,

data/lib/rigor/language_server.rb

@@ -3,11 +3,10 @@
 module Rigor
   # The Language Server subsystem. See
   # `docs/design/20260517-language-server.md` for the design.
-  # Slice 1 ships the namespace + a minimal {Server} lifecycle the
-  # `rigor lsp` CLI subcommand can drive. Later slices add the
-  # stdio JSON-RPC transport (slice 2), the BufferTable (slice 3),
-  # `publishDiagnostics` (slice 4), and the rest of the v1 capability
-  # surface.
+  # The full v1 capability surface (document sync, publishDiagnostics,
+  # hover, completion, sig-help, folding, selection, and watched-file
+  # invalidation) is implemented. This module is the namespace and
+  # require entry point for the subsystem.
   module LanguageServer
   end
 end

data/lib/rigor/plugin/base.rb

@@ -18,10 +18,11 @@ module Rigor
     # overrides {#init} to wire up any state it needs from the
     # injected service container.
     #
-    # Slice 1 ships only the registration / loading plumbing. The
-    # protocol hooks (dynamic-return contributions, type-specifying
-    # contributions, dynamic reflection) land in subsequent v0.1.0
-    # slices and arrive as additional methods on this class.
+    # This class implements all plugin protocol hooks: per-call
+    # return-type contributions (`dynamic_return`), narrowing-fact
+    # contributions (`type_specifier`), AST node rules (`node_rule`),
+    # and producer/cache hooks. Cumulative implementation per the
+    # ADR-37 / ADR-52 slice chain.
     #
     # Example plugin:
     #
@@ -543,10 +544,11 @@ module Rigor
       #
       # `path` is the analysed file path; `scope` is the entry
       # `Rigor::Scope` after `ScopeIndexer` ran; `root` is the
-      # parsed `Prism::Node` root. Plugin authors traverse `root`
-      # themselves if they need node-scoped rules — the
-      # `Rule<TNode>` API ADR-2 § "Custom rules" mentions stays
-      # deferred to v0.1.x.
+      # parsed `Prism::Node` root. Plugin authors can traverse
+      # `root` themselves or declare rules via the `.node_rule` DSL
+      # (ADR-37, shipped). The PHPStan-style `Rule<TNode>` base
+      # class mentioned in ADR-2 was superseded by the block-based
+      # `.node_rule` DSL.
       #
       # Default returns `[]` so plugins that contribute through
       # other channels (e.g. slice-4 narrowing contributions,

data/lib/rigor/plugin/macro/block_as_method.rb

@@ -29,10 +29,9 @@ module Rigor
       # class-level methods whose block argument runs as if it were
       # an instance method of the receiver.
       #
-      # Slice 1a (this file) is **the contract only**. The engine
-      # hook that consults registered entries and narrows
-      # `Scope#self_type` for a block whose enclosing call matches
-      # arrives in slice 1b.
+      # Engine wiring: `Inference::MacroBlockSelfType.narrow_self_type_for`
+      # (called from expression_typer.rb) consults registered entries
+      # and narrows `Scope#self_type` for matching block call sites.
       #
       # ## Fields
       #

data/lib/rigor/plugin/macro/heredoc_template.rb

@@ -68,13 +68,10 @@ module Rigor
       # to a later slice — the `returns:` declarations cost
       # nothing to write today and unlock precision then.
       #
-      # ## Slice 2a scope
-      #
-      # This file ships the value class only. Slice 2b wires the
-      # pre-pass that scans Tier C call sites + the
-      # `SyntheticMethodIndex` the dispatcher consults; slice 2c
-      # authors `plugins/rigor-dry-struct/` and
-      # `plugins/rigor-dry-types/` as the worked consumers.
+      # Engine wiring: `Inference::SyntheticMethodScanner` (slice 2b,
+      # `synthetic_method_scanner.rb`) consumes `manifest.heredoc_templates`.
+      # Worked consumers: `plugins/rigor-dry-struct/` and
+      # `plugins/rigor-dry-types/` (slice 2c).
       class HeredocTemplate
         NAME_PLACEHOLDER = "\#{name}"
 

data/lib/rigor/plugin/macro/trait_registry.rb

@@ -78,12 +78,9 @@ module Rigor
       #   facts (attr_reader / after_save / etc.); slice 3 emits
       #   only the module's plain instance methods.
       #
-      # ## Slice 3a scope
-      #
-      # This file ships the value class only. Slice 3b wires the
-      # scanner that walks Tier B call sites + the per-method
-      # explosion via `SyntheticMethodIndex`; slice 3c authors
-      # `plugins/rigor-devise/` model side as the worked consumer.
+      # Engine wiring: `Inference::SyntheticMethodScanner#collect_trait_registries`
+      # (slice 3b) walks Tier B call sites and explodes per-method
+      # entries. Worked consumer: `plugins/rigor-devise/` (slice 3c).
       class TraitRegistry
         REST_POSITION = :rest
 

data/lib/rigor/plugin/macro.rb

@@ -14,11 +14,10 @@ module Rigor
     # `nested_class_templates:`) and the substrate consumes them
     # to recognise the call shapes a library exposes to its users.
     #
-    # Slice 1a (this file's first delivery) ships the Tier A value
-    # class only. The other tiers' value classes + their manifest
-    # slots arrive in subsequent slices per ADR-16 § Implementation
-    # slicing. The namespace is reserved here so subsequent slices
-    # add files alongside `block_as_method.rb` without churn.
+    # Tier A (`BlockAsMethod`), Tier B (`TraitRegistry`), Tier C
+    # (`HeredocTemplate`), and ADR-36 nested-class emission
+    # (`NestedClassTemplate`) value classes are all shipped here.
+    # Engine wiring lives in `lib/rigor/inference/`.
     #
     # Per ADR-16 § WD13, substrate-produced output ships at a
     # **floor** in v0.1.x ("substrate-affected code parses cleanly