rigortype 0.4.6 → 0.4.7

data/lib/rigor/sig_gen/write_result.rb

@@ -11,7 +11,7 @@ module Rigor
     # - `target_path` — `.rbs` file the writer was responsible for (`nil` when the source path falls outside
     #   the project signature tree, in which case `action` is `:skipped_outside_sig_root`).
     # - `action` — one of `:created` / `:updated` / `:noop` / `:skipped_outside_sig_root` /
-    #   `:skipped_invalid_rbs` / `:skipped_invalid_encoding`.
+    #   `:skipped_invalid_rbs` / `:skipped_invalid_encoding` / `:skipped_unparseable`.
     # - `applied` — the {MethodCandidate}s that actually landed on disk.
     # - `replaced` — the subset of `applied` that replaced an existing declaration rather than adding one
     #   (`--overwrite`'s tighter returns, and inline updates).
@@ -23,16 +23,20 @@ module Rigor
     #   target declaration already carries annotations, so its bytes were left alone
     #   (`sig.effect.left-unreadable`; see {Writer#splice_annotations}). The signature line itself was
     #   still updated.
+    # - `repaired_headers` — the existing class or module headers the writer gave a generic class's type
+    #   parameters (`"Array[unchecked out E]"`), because the file opened it with none (#2580).
     # - `error` — the refusal cause, when `action` is a refusal: for `:skipped_invalid_rbs` the file the writer
     #   assembled does not parse, so it was NOT written (writing it would poison the project's sig tree — the
     #   consumer quarantines an unparseable `.rbs`, taking every other type in that file down with it); for
     #   `:skipped_invalid_encoding` the EXISTING target file is not valid UTF-8, so the writer refuses to merge
-    #   into content it cannot read faithfully.
+    #   into content it cannot read faithfully; for `:skipped_unparseable` the EXISTING target file does not parse
+    #   as RBS, so the writer refuses to merge into it (#2480).
     class WriteResult
-      attr_reader :source_path, :target_path, :action, :applied, :skipped, :error, :left_unreadable, :replaced
+      attr_reader :source_path, :target_path, :action, :applied, :skipped, :error, :left_unreadable, :replaced,
+                  :repaired_headers
 
       def initialize(source_path:, target_path:, action:, applied: [], skipped: [], error: nil, # rubocop:disable Metrics/ParameterLists
-                     left_unreadable: [], replaced: [])
+                     left_unreadable: [], replaced: [], repaired_headers: [])
         @source_path = source_path
         @target_path = target_path
         @action = action
@@ -41,6 +45,7 @@ module Rigor
         @error = error
         @left_unreadable = left_unreadable.freeze
         @replaced = replaced.freeze
+        @repaired_headers = repaired_headers.freeze
         freeze
       end
 
@@ -51,14 +56,20 @@ module Rigor
           action: action.to_s,
           applied: applied.map(&:to_h),
           skipped: skipped.map { |c, reason| c.to_h.merge(write_skip_reason: reason.to_s) }
-        }.tap do |h|
-          h[:error] = error if error
-          # Absent when nothing was replaced, so a run that only adds lines keeps its pre-#1076 payload.
-          h[:replaced] = replaced.map(&:to_h) unless replaced.empty?
-          # Absent rather than empty when nothing was left: an effects-off payload stays byte-identical
-          # to a pre-#391 one.
-          h[:effect_left_unreadable] = left_unreadable.map(&:to_h) unless left_unreadable.empty?
-        end
+        }.tap { |h| add_optional_entries(h) }
+      end
+
+      private
+
+      def add_optional_entries(hash)
+        hash[:error] = error if error
+        # Absent when nothing was replaced, so a run that only adds lines keeps its pre-#1076 payload.
+        hash[:replaced] = replaced.map(&:to_h) unless replaced.empty?
+        # Absent when no header was repaired (#2580), for the same reason.
+        hash[:repaired_headers] = repaired_headers unless repaired_headers.empty?
+        # Absent rather than empty when nothing was left: an effects-off payload stays byte-identical
+        # to a pre-#391 one.
+        hash[:effect_left_unreadable] = left_unreadable.map(&:to_h) unless left_unreadable.empty?
       end
     end
   end

data/lib/rigor/sig_gen/writer.rb

@@ -4,6 +4,7 @@ require "fileutils"
 require "rbs"
 
 require_relative "classification"
+require_relative "generic_header_scan"
 require_relative "layout_index"
 require_relative "superclass_spelling"
 require_relative "write_result"
@@ -15,7 +16,8 @@ module Rigor
     #
     # ADR-14 slice 2: the writer parses the target with `RBS::Parser` to find the matching class declaration and
     # inserts new method declarations just before the class's closing `end` keyword. Existing declarations are
-    # NEVER touched unless `--overwrite` is set AND the candidate's classification is `tighter-return`.
+    # NEVER touched unless `--overwrite` is set and the candidate is eligible for replacement (see
+    # {#eligible_for_replacement?}).
     #
     # The slice does NOT re-render the whole file through `RBS::Writer`. That would lose comments / blank-line
     # formatting per upstream design; the byte-range insertion approach taken here preserves untouched
@@ -32,9 +34,18 @@ module Rigor
 
       # Per-`update_existing` accumulator. The merge_class helper mutates `source` / `decls` / `applied` /
       # `skipped` in place as each class is processed so the next class sees the latest byte positions.
-      MergeState = Struct.new(:source, :decls, :applied, :skipped, :left_unreadable, :replaced, keyword_init: true)
+      MergeState = Struct.new(:source, :decls, :applied, :skipped, :left_unreadable, :replaced, :repaired_headers,
+                              :target, keyword_init: true)
       private_constant :MergeState
 
+      # The target routing this writer applies; the generator maps candidates through it to ask {#accepts_target?}.
+      attr_reader :path_mapper
+
+      # #2605 — the generic classes whose bare headers the last {#write_all} (or {#write}) left bare, because a
+      # body names one of the parameters: `{ class:, targets:, blocking: [{ target:, names: }] }` each
+      # ({GenericHeaderScan#left_bare}).
+      attr_reader :left_bare
+
       # @param dry_run — assemble and validate every target exactly as a write would, and report it, without
       #   creating or changing a file. `sig-gen --check` (ADR-112 WD4) is this, so it can only ever disagree
       #   with `--write` about the disk, never about the content.
@@ -47,6 +58,15 @@ module Rigor
         @global_namespace_kinds = {}
         # Run-level qualified-class-name => superclass-token view, same lifecycle as `@global_namespace_kinds`.
         @global_superclasses = {}
+        # #2436 — the target being rendered's view of {MethodCandidate#class_type_params}, set per target.
+        @type_params = {}
+        # #2603/#2605 — the run-wide repair decision {#write_all} reads from the sig root before writing: the
+        # classes cleared for repair with their spelling, and the classes held back. {#write} leaves both empty and
+        # decides per file.
+        @scan_repairs = {}
+        @held_back = []
+        @left_bare = []
+        @repair_targets = []
       end
 
       # Process the full candidate list by resolving each candidate's target sig file via the path mapper (which
@@ -56,31 +76,94 @@ module Rigor
       # ADR-14 follow-up: this is the consolidated-layout entry point. The legacy `write(source_path,
       # candidates)` below assumes all candidates share a target and remains for spec convenience.
       #
+      # @param header_spelling — called with a class name, returns the header spelling of a generic class the run
+      #   does not stamp (#2603: a bare header in a file no candidate routes to); the generator's
+      #   {Generator#generic_header_spelling}. Without it only the run's stamp counts.
       # @return one per target sig file.
-      def write_all(candidates)
+      def write_all(candidates, header_spelling: nil)
         emittable = candidates.select { |c| EMITTABLE.include?(c.classification) }
-        return [] if emittable.empty?
+        scan_generic_headers(candidates, header_spelling)
 
         @global_namespace_kinds = build_namespace_kinds(candidates)
         @global_superclasses = build_superclasses(candidates)
-        grouped = emittable.group_by do |c|
-          @path_mapper.target_for(c.path, class_name: c.class_name, method_name: c.method_name, kind: c.rbs_kind)
+        grouped = emittable.group_by { |c| target_of(c) }
+        results = grouped.map { |target, group| write_target(target, group) }
+        results + repair_only_results(candidates, grouped.keys.map { |target| target.expand_path.to_s })
+      end
+
+      def target_of(candidate)
+        @path_mapper.target_for(candidate.path, class_name: candidate.class_name,
+                                                method_name: candidate.method_name, kind: candidate.rbs_kind)
+      end
+      private :target_of
+
+      # Issues #2603 and #2605 — reads every file under the signature paths for bare openings of generic classes
+      # before anything is written ({GenericHeaderScan}). A class is repaired in every file or in none: one bare
+      # opening rbs still rejects keeps the class failing, so repairing its other openings would be churn. Only files
+      # under the sig root are rewritten; a bare opening anywhere else holds its class back.
+      def scan_generic_headers(candidates, header_spelling)
+        stamp = merged_type_params(candidates)
+        scan = GenericHeaderScan.scan(sig_root: @path_mapper.sig_root_dir, signature_dirs: @path_mapper.signature_dirs,
+                                      spelling_for: ->(name) { stamp[name] || header_spelling&.call(name) })
+        @scan_repairs = scan.repairs
+        @held_back = scan.left_bare.map { |entry| entry.fetch(:class) }
+        @left_bare = scan.left_bare
+        @repair_targets = scan.repair_targets
+      end
+      private :scan_generic_headers
+
+      # The files with a bare header to repair that no emitted member routes to: each gets the repair and nothing
+      # else (#2580), whether a skipped candidate routes to it or none does (#2603). The row names a candidate's
+      # source when one routes there. A file the writer would not open (not UTF-8, unparseable) is never listed.
+      def repair_only_results(candidates, written)
+        sources = candidates.each_with_object({}) do |candidate, acc|
+          acc[target_of(candidate).expand_path.to_s] ||= candidate.path if candidate.path
+        end
+        @repair_targets.filter_map do |path|
+          target = Pathname(path)
+          next if written.include?(target.expand_path.to_s) || !inside_sig_root?(target)
+
+          result = update_existing(sources[target.expand_path.to_s], target, [], repair_only: true)
+          result if %i[updated skipped_invalid_rbs].include?(result.action)
         end
-        grouped.map { |target, group| write_target(target, group) }
       end
+      private :repair_only_results
 
-      # @param candidates — only
-      #   emittable classifications (new-method /
-      #   tighter-return) are honoured; the caller is
-      #   responsible for filtering.
+      # @param candidates — only emittable classifications are honoured; `write` filters on `EMITTABLE` itself.
       def write(source_path, candidates)
         emittable = candidates.select { |c| EMITTABLE.include?(c.classification) }
         return WriteResult.new(source_path: source_path, target_path: nil, action: :noop) if emittable.empty?
 
+        @scan_repairs = {}
+        @held_back = []
+        @left_bare = []
         target = @path_mapper.target_for(source_path, class_name: emittable.first.class_name)
         write_target(target, emittable, source_path: source_path)
       end
 
+      # Whether the writer is sure to write `candidate`. A file the writer writes nothing to is left as it is, so a
+      # class shell riding on that file's candidates never reaches disk; the generator asks this before it counts
+      # a shell as declared (#2454). Only a new method is sure: without `--overwrite` the writer skips a tighter
+      # return or an inline overwrite whose method the target already declares. Counting too few only demotes a
+      # subclass, which is the output before #2454.
+      def self.writes?(candidate)
+        candidate.classification == Classification::NEW_METHOD
+      end
+
+      # Whether {#write_target} would write to `target` at all, asked before any candidate is rendered (#2461): a
+      # target inside the sig root that is missing (the create path), or that exists, is valid UTF-8 and parses.
+      # {#update_existing} refuses an unparseable or mis-encoded file and leaves it untouched, so a class shell on it
+      # never reaches disk. A spliced result {RbsValidity} rejects is a writer defect and is not predicted here.
+      def accepts_target?(target)
+        return false unless inside_sig_root?(target)
+        return true unless target.exist?
+
+        source = target.read
+        source.valid_encoding? && !parse_signature(source).nil?
+      rescue SystemCallError
+        false
+      end
+
       # Whether `proposed` has STRICTLY FEWER bare `untyped` tokens than `existing`. A count, not a slot-by-slot
       # comparison: it reads as "at least one more position is concrete", and does not prove that no concrete
       # position became `untyped` elsewhere. Word-boundary matching counts `untyped` only as a type token, not
@@ -157,10 +240,11 @@ module Rigor
         tree = build_namespace_tree(candidates, shells)
         kinds = merged_namespace_kinds(candidates)
         supers = merged_superclasses(candidates)
+        @type_params = merged_type_params(candidates)
         render_tree_nodes(tree, kinds, supers, 0)
       end
 
-      # Drains `class_shells` from every candidate; the generator's walker populates the same set on every
+      # Unions `class_shells` across every candidate; the generator's walker populates the same set on every
       # candidate produced from a given file (gap-#3 (e)).
       def collect_class_shells(candidates)
         shells = Set.new
@@ -202,6 +286,13 @@ module Rigor
         merged
       end
 
+      # #2436 — every candidate carries the run's map, so folding the target's candidates is the whole view.
+      def merged_type_params(candidates)
+        candidates.each_with_object({}) do |c, acc|
+          acc.merge!(c.class_type_params) if c.respond_to?(:class_type_params)
+        end
+      end
+
       def build_superclasses(candidates)
         candidates.each_with_object({}) do |candidate, acc|
           next unless candidate.respond_to?(:class_superclasses)
@@ -257,7 +348,7 @@ module Rigor
         indent = INDENT * depth
         qualified = (prefix + [node[:name]]).join("::")
         keyword = node_keyword(node, kinds, qualified)
-        header = "#{keyword} #{node[:name]}#{superclass_suffix(keyword, supers, qualified)}"
+        header = "#{keyword} #{node[:name]}#{@type_params[qualified]}#{superclass_suffix(keyword, supers, qualified)}"
         body = render_tree_node_body(node, kinds, supers, depth, prefix)
         "#{indent}#{header}\n#{body}#{indent}end\n"
       end
@@ -293,13 +384,12 @@ module Rigor
         :module
       end
 
-      def update_existing(source_path, target, candidates)
+      def update_existing(source_path, target, candidates, repair_only: false)
         source = target.read
         # Pre-parser encoding guard, mirroring `Environment::RbsLoader.invalid_encoding?`: handed invalid
         # UTF-8, `RBS::Parser` raises a bare `ArgumentError` on rbs 4.1 (not the `ParsingError` that
         # `parse_signature` below rescues) and could hang outright on the older releases the gemspec
-        # supports. The refusal is loud — unlike an unparseable file (`:noop`, surfaced by `rigor check`'s
-        # own quarantine warning), a mojibake file would otherwise fail with a stack trace naming neither
+        # supports. The refusal is loud — a mojibake file would otherwise fail with a stack trace naming neither
         # the file nor the fix.
         unless source.valid_encoding?
           return WriteResult.new(source_path: source_path, target_path: target,
@@ -307,16 +397,19 @@ module Rigor
                                  error: "#{target} is not valid UTF-8")
         end
 
-        decls = parse_signature(source)
-        return WriteResult.new(source_path: source_path, target_path: target, action: :noop) if decls.nil?
-
-        state = MergeState.new(source: source, decls: decls, applied: [], skipped: [], left_unreadable: [],
-                               replaced: [])
-        merge_candidates(state, candidates)
+        # An existing file that does not parse is refused like a mis-encoded one, not skipped as `:noop` (#2480):
+        # `--check` must fail on it, because a `--write` that cannot touch the file is not an up-to-date `sig/`.
+        # `rigor check` quarantines such a file whole; this refusal names it at the sig-gen boundary too.
+        decls, parse_detail = parse_target_signature(target, source)
+        if decls.nil?
+          return WriteResult.new(source_path: source_path, target_path: target,
+                                 action: :skipped_unparseable,
+                                 error: "#{target} does not parse as RBS: #{parse_detail}")
+        end
 
-        action = state.applied.empty? ? :noop : :updated
-        unless action == :updated
-          return WriteResult.new(source_path: source_path, target_path: target, action: action,
+        state = merged_state(source, decls, candidates, repair_only, target)
+        unless state_changed?(state)
+          return WriteResult.new(source_path: source_path, target_path: target, action: :noop,
                                  applied: state.applied, skipped: state.skipped,
                                  left_unreadable: state.left_unreadable)
         end
@@ -333,8 +426,9 @@ module Rigor
 
         target.write(state.source) unless @dry_run
         WriteResult.new(source_path: source_path, target_path: target,
-                        action: action, applied: state.applied, skipped: state.skipped,
-                        left_unreadable: state.left_unreadable, replaced: state.replaced)
+                        action: :updated, applied: state.applied, skipped: state.skipped,
+                        left_unreadable: state.left_unreadable, replaced: state.replaced,
+                        repaired_headers: state.repaired_headers)
       end
 
       # Applies every class group, then every requested shell, then normalises the layout the three steps
@@ -343,12 +437,89 @@ module Rigor
         supers = merged_superclasses(candidates)
         kinds = merged_namespace_kinds(candidates)
         shells = collect_class_shells(candidates)
+        @type_params = merged_type_params(candidates)
         groups = candidates.group_by(&:class_name)
         # Ancestors first, so `Foo` is created (or found) before `Foo::Bar` looks for a parent to nest under.
         # A plain sort suffices: a name always sorts before every name it is a strict prefix of.
         groups.keys.sort.each { |name| merge_class(state, name, groups.fetch(name), kinds, supers) }
         merge_class_shells(state, shells, kinds, supers)
         collapse_nested_declarations(state, groups.keys + shells.to_a)
+        # Last, so the members this run merged count towards {#shadowed_after_merge?}.
+        repair_generic_headers(state, state.target)
+      end
+
+      # Issue #2580 — a declaration this file already holds for a class the loaded RBS declares generic, opened
+      # with no type parameters at all (`class Array`, as sig-gen wrote it before #2436), is a guaranteed
+      # `RBS::GenericParameterMismatchError`: rbs requires every declaration of a class to repeat the first one's
+      # parameters, and the class, plus every class whose ancestry reaches it (`Object` through `Kernel`), then
+      # fails its definition build. Writing more members into that header would keep the file broken, so the
+      # header gets the same spelling a new header would ({Generator#stamp_generic_reopenings}: plain
+      # parameters only). A header that spells parameters of its own is the project's and is left alone, as is
+      # every class neither the run's stamp nor {#write_all}'s scan names.
+      #
+      # A declaration whose body names a type like one of the parameters (`def old: () -> E` for a project class
+      # `E`) is left bare: under `class Array[unchecked out E]` that `E` would bind to the parameter, silently
+      # changing what the member says. The body is matched as text, so a comment or a nested declaration that
+      # spells the name also keeps the header bare, which is the state the file was already in; a method type that
+      # declares the name as its own parameter (`def m: [E] (E) -> E`) does not (#2605).
+      #
+      # Under {#write_all} the class is repaired in every file under the sig root or in none ({GenericHeaderScan},
+      # #2605): a class held back there is not repaired here, and a class the run does not stamp is repaired with the
+      # scan's spelling (#2603). The check below runs again after the merge, so a member this run merged counts
+      # too; the generator anchors a member's type that a parameter would capture (#2436), so it holds back a class
+      # the scan cleared only for a member written without that anchor, and is then reported in {#left_bare}.
+      # `repaired_headers` gets one entry per declaration repaired.
+      def repair_generic_headers(state, target)
+        spellings = @scan_repairs.merge(@type_params).except(*@held_back)
+        spellings.keys.sort.each do |name|
+          spelling = spellings.fetch(name)
+          bare = find_class_decls(state.decls, name).select { |d| d.type_params.empty? && d.location&.[](:name) }
+          next if bare.empty? || shadowed_after_merge?(state.source, bare, name, spelling, target)
+
+          insert_type_params(state, bare, spelling)
+          bare.each { state.repaired_headers << "#{name}#{spelling}" }
+        end
+      end
+
+      # Whether any of `bare` names one of the parameters `spelling` declares ({GenericHeaderScan.shadowing_names});
+      # each such opening is recorded in {#left_bare}.
+      def shadowed_after_merge?(source, bare, name, spelling, target)
+        params = GenericHeaderScan.parameter_names(spelling)
+        return true if params.nil?
+
+        blocking = bare.filter_map do |decl|
+          names = GenericHeaderScan.shadowing_names(source, decl, params)
+          { target: target.to_s, reason: "names_parameter", names: names } unless names.empty?
+        end
+        return false if blocking.empty?
+
+        @left_bare << { class: name, targets: [target.to_s], blocking: blocking }
+        true
+      end
+
+      # Splices `spelling` right after each declaration's name, last one first so earlier offsets stay valid.
+      def insert_type_params(state, decls, spelling)
+        decls.map { |d| d.location[:name].end_pos }.sort.reverse_each do |pos|
+          state.source = state.source[0...pos] + spelling + state.source[pos..]
+        end
+        state.decls = parse_signature(state.source) || state.decls
+      end
+
+      def merged_state(source, decls, candidates, repair_only, target)
+        state = MergeState.new(source: source, decls: decls, applied: [], skipped: [], left_unreadable: [],
+                               replaced: [], repaired_headers: [], target: target)
+        repair_only ? repair_only_candidates(state, candidates) : merge_candidates(state, candidates)
+        state
+      end
+
+      def state_changed?(state)
+        !(state.applied.empty? && state.repaired_headers.empty?)
+      end
+
+      # {#repair_only_results}' merge step: the run's stamp, and the header repair alone.
+      def repair_only_candidates(state, candidates)
+        @type_params = merged_type_params(candidates)
+        repair_generic_headers(state, state.target)
       end
 
       # ADR-14 gap-#3 (e): for every requested class shell that isn't already declared in the target file,
@@ -401,7 +572,9 @@ module Rigor
         parent_name = segments[0...-1].join("::")
         parent = find_class_decl(state.decls, parent_name)
         decl = parent && find_class_decl(state.decls, qualified)
-        return if decl.nil? || overlapping?(parent, decl)
+        # A rooted declaration (`module A; class ::B::C`) keeps the layout the user wrote: cutting it out of its
+        # enclosing module would leave that module empty, so the member merges in place instead.
+        return if decl.nil? || overlapping?(parent, decl) || decl.name.to_s.start_with?("::")
 
         region = decl_region(state.source, decl)
         block = region && relocated_block(state.source, decl, parent, segments.last, region)
@@ -560,6 +733,15 @@ module Rigor
         nil
       end
 
+      # Parses an EXISTING target, naming it as the buffer so the parse error carries `path:line:col` (a bare
+      # String would be named `a.rbs`). Returns `[decls, nil]`, or `[nil, first_line_of_message]` on a parse error.
+      def parse_target_signature(target, source)
+        _, _, decls = RBS::Parser.parse_signature(RBS::Buffer.new(name: target.to_s, content: source))
+        [decls, nil]
+      rescue RBS::ParsingError => e
+        [nil, e.message.to_s.lines.first.to_s.strip]
+      end
+
       def merge_class(state, class_name, methods, kinds, supers)
         decl = find_class_decl(state.decls, class_name)
         if decl.nil?
@@ -586,11 +768,10 @@ module Rigor
         decls.each do |decl|
           next unless decl.is_a?(RBS::AST::Declarations::Class) || decl.is_a?(RBS::AST::Declarations::Module)
 
-          local = decl.name.to_s.sub(/\A::/, "")
-          full = prefix.empty? ? local : "#{prefix.join('::')}::#{local}"
-          return decl if full == qualified_name
+          path = ::Rigor::Environment::RbsLoader.declared_class_path(decl, prefix)
+          return decl if path.join("::") == qualified_name
 
-          nested = find_class_decl_in(decl.members, prefix + [local], qualified_name)
+          nested = find_class_decl_in(decl.members, path, qualified_name)
           return nested if nested
         end
         nil
@@ -602,10 +783,9 @@ module Rigor
         decls.each do |decl|
           next unless decl.is_a?(RBS::AST::Declarations::Class) || decl.is_a?(RBS::AST::Declarations::Module)
 
-          local = decl.name.to_s.sub(/\A::/, "")
-          full = prefix.empty? ? local : "#{prefix.join('::')}::#{local}"
-          found << decl if full == qualified_name
-          find_class_decls(decl.members, qualified_name, prefix + [local], found)
+          path = ::Rigor::Environment::RbsLoader.declared_class_path(decl, prefix)
+          found << decl if path.join("::") == qualified_name
+          find_class_decls(decl.members, qualified_name, path, found)
         end
         found
       end
@@ -669,7 +849,7 @@ module Rigor
       # name, slices out the old declaration's source range and substitutes the new RBS one-liner. Members that
       # are not `MethodDefinition`s are left alone.
       #
-      # Two candidate classifications are eligible for replacement under `--overwrite`:
+      # Under `--overwrite`, an inline overwrite is always eligible, and so are two other classifications:
       #
       # 1. `TIGHTER_RETURN` — the classifier already proved the new return type is a strict subtype of the
       #    declared one (with lenience guards passed).

data/lib/rigor/type/acceptance_router.rb

@@ -6,8 +6,8 @@ module Rigor
     #
     # Every carrier's acceptance check is the same fixed forwarding on `self` —
     # `Inference::Acceptance.accepts(self, other, mode: mode)` — so it lived as an identical copy in
-    # fourteen carriers. The one exception is `Type::App`, which forwards on its reduced `bound` type rather
-    # than `self`; it keeps its own `accepts` and does not include this.
+    # every carrier that includes it. The one exception is `Type::App`, which forwards on its reduced `bound`
+    # type rather than `self`; it keeps its own `accepts` and does not include this.
     module AcceptanceRouter
       def accepts(other, mode: :gradual)
         Inference::Acceptance.accepts(self, other, mode: mode)

data/lib/rigor/type/accepts_result.rb

@@ -9,7 +9,7 @@ module Rigor
     # answer alongside the boundary mode the answer was computed under and an ordered list of textual
     # reasons describing which rules fired.
     #
-    # AcceptsResult is the dual of `SubtypeResult` (Slice 5+). Acceptance answers "is `other` passable to
+    # AcceptsResult is the dual of the planned `SubtypeResult`. Acceptance answers "is `other` passable to
     # `self` at a method-parameter or assignment boundary?", consulting the gradual-typing rules in
     # docs/type-specification/value-lattice.md when `mode` is `:gradual`, and the strict subset relation
     # when `mode` is `:strict`. Phase 2c ships full `:gradual` semantics; `:strict` is reserved for later

data/lib/rigor/type/app.rb

@@ -17,13 +17,11 @@ module Rigor
     # (use a plain type alias instead).
     #
     # `bound` is a `Rigor::Type` representing the value Rigor MUST erase to when this `App` cannot be
-    # reduced — registered at `%a{rigor:v1:hkt_register}` time, defaulting to
-    # `Rigor::Type::Dynamic[Rigor::Type::Top]` per ADR-20 D5 / WD2. It also drives the lattice probes
-    # (`top` / `bot` / `dynamic`) and the acceptance fallback while no reduction is wired (Slice 1).
+    # reduced — registered at `%a{rigor:v1:hkt_register}` time, defaulting to the untyped top per ADR-20 D5 /
+    # WD2. It also drives the lattice probes (`top` / `bot` / `dynamic`) and `accepts`.
     #
-    # Slice 1 ships the carrier as **opaque**: every operation delegates to `bound` since no reduction
-    # surface exists yet. Slice 2 introduces the conditional / indexed-access evaluator that reduces `App`
-    # to its registered body before delegating; the carrier shape stays identical.
+    # The carrier is opaque: those operations delegate to `bound`, and {#reduce} is the one path that unfolds
+    # the application to its registered body first (ADR-20 Slice 2a).
     #
     # Display form per ADR-20 OQ5: bare RBS-style `uri[arg1, arg2]`, not the wrapped `App[uri, [arg1,
     # arg2]]` faithful form. Two `App` values are structurally equal iff their `uri`, `args`, AND `bound`

data/lib/rigor/type/combinator.rb

@@ -245,8 +245,8 @@ module Rigor
       end
 
       # `literal-string` — a `String` that is statically known to come from a source-code literal (or a
-      # composition of literals). v0.0.9 tracks this flow through interpolation `"#{...}"`, leaving
-      # propagation through `+` / `<<` to a later slice. Every `Constant<String>` is implicitly
+      # composition of literals). Interpolation `"#{...}"` and `+` / `*` composition keep
+      # the flow (see {literal_string_compatible?}). Every `Constant<String>` is implicitly
       # literal-string-compatible; the carrier exists for cases where the concrete value is unknown but
       # literal-ness has been established (an RBS::Extended `return: literal-string` annotation, or
       # interpolation over literal-bearing parts).
@@ -433,8 +433,7 @@ module Rigor
       # - `Type::Tuple[A, B, C]` → `Constant<0> | Constant<1> | Constant<2>`.
       # - `Type::Nominal["Hash", [K, V]]` → `K` (untyped if absent).
       # - `Type::Nominal["Array", [E]]` → `non-negative-int`.
-      # - `Type::Constant` whose value is a Hash / Array / Range — project through the literal's
-      #   per-element keys.
+      # - `Type::Constant` wrapping a Range with an Integer begin — `non-negative-int`.
       #
       # Other inputs (`Top`, `Dynamic`, untyped Nominals, `Union`, `Refined`, `Difference`,
       # `Intersection`) project to `top` so the type function always returns a value — callers may narrow
@@ -456,8 +455,7 @@ module Rigor
       # - `Type::Tuple[A, B, C]` → `A | B | C`.
       # - `Type::Nominal["Hash", [K, V]]` → `V` (untyped if absent).
       # - `Type::Nominal["Array", [E]]` → `E` (untyped if absent).
-      # - `Type::Constant` whose value is a Hash / Array / Range — union of `Constant<…>` for each
-      #   element.
+      # - `Type::Constant` wrapping an integer Range — the `IntegerRange` it spans.
       def value_of(type)
         case type
         when HashShape then hash_shape_values(type)
@@ -528,8 +526,7 @@ module Rigor
       # Phase A handles `Type::HashShape` (literal-key K). Phase B (slice 5) extends to `Type::Tuple`
       # (integer-index K) — `pick_of[Tuple[A, B, C], 0 | 2]` evaluates to `Tuple[A, C]`. Non-shape inputs
       # (`Type::Nominal`, etc.) return `type` unchanged ("lossy degradation"; the
-      # `dynamic.shape.lossy-projection` diagnostic that flags the boundary lands when caller-side
-      # diagnostic threading arrives).
+      # `dynamic.shape.lossy-projection` diagnostic that flags the boundary).
       def pick_of(type, keys)
         case type
         when HashShape then hash_shape_pick(type, keys)
@@ -597,8 +594,7 @@ module Rigor
       # site where the projection was authored.
       #
       # `HashShape` and `Tuple` carry shape-level information the projections honour; every other carrier
-      # is lossy. Slice 5b wires diagnostic emission through `RbsExtended` / parser callers; this
-      # predicate stands alone in slice 5 for unit-test coverage and future composition.
+      # is lossy.
       def shape_projection_lossy?(type)
         !type.is_a?(HashShape) && !type.is_a?(Tuple)
       end
@@ -792,9 +788,9 @@ module Rigor
           top
         end
 
-        # `Type::Constant` only carries scalar literals (Integer / Float / String / Symbol / Range /
-        # Rational / Complex / true / false / nil); Array and Hash literals become Tuple / HashShape
-        # carriers earlier in the typer. Range is the only scalar with meaningful key/value projections.
+        # `Type::Constant` only carries scalar literals (`Constant::SCALAR_CLASSES`); Array and Hash literals
+        # become Tuple / HashShape carriers earlier in the typer. Range is the only scalar with meaningful
+        # key/value projections.
         def constant_keys(value)
           return non_negative_int if value.is_a?(Range) && value.begin.is_a?(Integer)
 

data/lib/rigor/type/constant.rb

@@ -8,9 +8,8 @@ require_relative "plain_lattice"
 module Rigor
   module Type
     # A literal carrier under ADR-3 OQ1 Option C (Hybrid). Wraps a Ruby literal value of one of the
-    # supported immutable-ish classes. Compound literal shapes (Tuple, HashShape, Record) get dedicated
-    # classes in later slices; Range is carried only when both static endpoints are known enough for
-    # tuple slicing.
+    # supported immutable-ish classes. Compound literal shapes (Tuple, HashShape) have their own classes;
+    # Range is carried only when both static endpoints are known enough for tuple slicing.
     #
     # See docs/adr/4-type-inference-engine.md for the tentative answer to the open question and
     # docs/type-specification/rigor-extensions.md for the refinement neighbourhood this carrier lives in.
@@ -74,12 +73,12 @@ module Rigor
 
       # RBS supports `Literal` types for booleans, nil, integer literals (positive and negative), symbol
       # literals, and string literals. Erasing to these preserves the carrier's precision at the RBS
-      # boundary — `Constant<64>` round-trips as `64`, not as `Integer` — and
+      # boundary — the constant 64 round-trips as `64`, not as `Integer` — and
       # `RbsTypeTranslator#translate_literal` already maps the parsed RBS Literal back to `Constant`.
       # Scalar carriers without RBS Literal support (Float, Range, Rational, Complex, Regexp, Pathname)
       # keep their pre-existing widen-to-class-name behaviour because RBS rejects their literal spellings
       # as syntax errors. `Range` is generic (`Range[out E]`), and a bare `Range` fails `rbs validate`, so
-      # it carries the class of its endpoints, or `untyped` when both are nil (#1891). `Set[unchecked out A]` is
+      # it carries the class of its endpoints, or `untyped` when both are nil (#1891). `Set` is
       # generic too, and a set is mutable: the constant's elements are only what it held when it was built, and
       # `x << "a"` adds a member they do not name. It erases to `Set[untyped]`, as an Array or Hash literal's
       # element type is widened rather than pinned (#2177).