rigortype 0.3.9 → 0.4.0

data/lib/rigor/cli/type_of_command.rb

@@ -13,6 +13,7 @@ require_relative "../inference/scope_indexer"
 require_relative "../inference/precision_scanner"
 require_relative "../source/node_children"
 require_relative "type_of_renderer"
+require_relative "type_of_template_probe"
 require_relative "command"
 require_relative "options"
 require_relative "../project_environment"
@@ -28,10 +29,15 @@ module Rigor
     # type-of UX (extra flags, watch mode, streaming output) without bloating the CLI shell. Output formatting is
     # delegated to {TypeOfRenderer}.
     class TypeOfCommand < Command
+      include TypeOfTemplateProbe
+
       USAGE = "Usage: rigor type-of [options] FILE:LINE[:COL] [FILE:LINE[:COL] ...]"
 
-      Result = Data.define(:file, :line, :column, :node, :type, :tracer, :enumeration) do
-        def initialize(enumeration: nil, **rest)
+      # `location_mapper` is set for a template unit's result (#1040): the `--trace` fallback locations are
+      # positions in the COMPILED Ruby, and the mapper turns one into the `[template_line, column_or_nil]`
+      # the user can find in the file they named.
+      Result = Data.define(:file, :line, :column, :node, :type, :tracer, :enumeration, :location_mapper) do
+        def initialize(enumeration: nil, location_mapper: nil, **rest)
           super
         end
       end
@@ -106,6 +112,14 @@ module Rigor
         physical = buffer ? buffer.resolve(file) : file
         return 1 unless file_exists?(buffer ? physical : file)
 
+        unit_probe = template_unit_probe(file, base_scope.environment, buffer)
+        return unit_probe if unit_probe.is_a?(Integer)
+
+        if unit_probe
+          context = { configuration: configuration, base_scope: base_scope, options: options }
+          return resolve_template(file, physical, unit_probe, indexed_targets, context)
+        end
+
         source = File.read(physical)
         parse_result = Prism.parse(source, filepath: file, version: configuration.target_ruby)
         return 1 if parse_errors?(parse_result, file)
@@ -191,11 +205,11 @@ module Rigor
         end
       end
 
-      def type_result(file, line, column, node, scope_index, options, enumeration: nil)
+      # `presentation` is the Result's optional `enumeration:` / `location_mapper:`.
+      def type_result(file, line, column, node, scope_index, options, **presentation)
         tracer = options[:trace] ? Inference::FallbackTracer.new : nil
         type = scope_index[node].type_of(node, tracer: tracer)
-        Result.new(file: file, line: line, column: column, node: node, type: type, tracer: tracer,
-                   enumeration: enumeration)
+        Result.new(file: file, line: line, column: column, node: node, type: type, tracer: tracer, **presentation)
       end
 
       # Builds the plugin-aware environment relative to the probed file, so the reported type matches what `rigor

data/lib/rigor/cli/type_of_renderer.rb

@@ -84,7 +84,7 @@ module Rigor
           @out.puts("fallbacks: none")
         else
           @out.puts("fallbacks (#{tracer.size}):")
-          tracer.each { |event| @out.puts("  - #{format_fallback_text(event, result.file)}") }
+          tracer.each { |event| @out.puts("  - #{format_fallback_text(event, result)}") }
         end
       end
 
@@ -118,21 +118,31 @@ module Rigor
           type: result.type.describe,
           erased: result.type.erase_to_rbs
         }
-        payload[:fallbacks] = result.tracer.map { |event| fallback_to_h(event) } if result.tracer
+        payload[:fallbacks] = result.tracer.map { |event| fallback_to_h(event, result) } if result.tracer
         payload
       end
 
-      def format_fallback_text(event, file)
-        "#{event.node_class} (#{event.family}) @ #{location_text(event.location, file)}"
+      def format_fallback_text(event, result)
+        "#{event.node_class} (#{event.family}) @ #{location_text(event.location, result)}"
       end
 
-      def location_text(location, file)
+      def location_text(location, result)
         return "<no location>" unless location.respond_to?(:start_line)
 
-        "#{file}:#{location.start_line}:#{location.start_column + 1}"
+        line, column = fallback_position(location, result)
+        column ? "#{result.file}:#{line}:#{column}" : "#{result.file}:#{line}"
       end
 
-      def fallback_to_h(event)
+      # A template unit's result (#1040) maps the compiled location back; a column that names nothing in the
+      # template is left out rather than printed as a column of bytes the user never wrote.
+      def fallback_position(location, result)
+        mapper = result.location_mapper
+        return [location.start_line, location.start_column + 1] if mapper.nil?
+
+        mapper.call(location)
+      end
+
+      def fallback_to_h(event, result)
         hash = {
           node_class: event.node_class.name,
           family: event.family,
@@ -140,8 +150,9 @@ module Rigor
         }
         location = event.location
         if location.respond_to?(:start_line)
-          hash[:line] = location.start_line
-          hash[:column] = location.start_column + 1
+          line, column = fallback_position(location, result)
+          hash[:line] = line
+          hash[:column] = column if column
         end
         hash
       end

data/lib/rigor/cli/type_of_template_probe.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "../analysis/template_unit_paths"
+require_relative "../analysis/template_unit_positions"
+require_relative "../analysis/template_units"
+require_relative "../inference/precision_scanner"
+require_relative "../inference/scope_indexer"
+require_relative "../source/node_locator"
+
+module Rigor
+  class CLI
+    # #1040 — `rigor type-of` against a **template unit**: a file a loaded plugin compiles into Ruby.
+    #
+    # Before this the command read the template from disk and parsed its bytes as Ruby, so an ERB view
+    # exited 1 on a parse error and an identity-transformed one answered about the wrong node under an
+    # unseeded scope. A template path now takes the path `rigor check` takes: the run's
+    # {Analysis::TemplateUnits} index is built, the COMPILED source is parsed with the unit's `scopes:`, the
+    # file scope is seeded with the unit's `self`, locals and ivars, and the requested template position is
+    # resolved through {Analysis::TemplateUnitPositions} — which declines, with a message, whenever the
+    # position does not denote exactly one compiled node.
+    #
+    # Mixed into {TypeOfCommand}; a path no loaded plugin claims never reaches anything here, so a `.rb`
+    # probe does not build the index or change a byte of its output.
+    module TypeOfTemplateProbe
+      # Why a template position has no answer, keyed by {Analysis::TemplateUnitPositions#node_at}'s reasons.
+      DECLINE_MESSAGES = {
+        no_compiled_line: "the template compiler emitted no Ruby for this line",
+        not_verbatim: "the position is in template markup, or in code the template compiler rewrote " \
+                      "rather than copied, so no compiled expression is made of the bytes there",
+        ambiguous: "the bytes there are template markup, or code the compiler copied to more than one " \
+                   "place, so the position does not name a single compiled expression"
+      }.freeze
+      private_constant :DECLINE_MESSAGES
+      Ractor.make_shareable(DECLINE_MESSAGES)
+
+      private
+
+      # The unit `file` compiles to, `nil` for a path that is not a template unit (the caller probes it as
+      # Ruby), or an exit status after reporting a template the claiming plugin could not compile.
+      def template_unit_probe(file, environment, buffer)
+        registry = environment.plugin_registry
+        return nil unless template_claimed?(registry, file)
+
+        units = (@template_units ||= Analysis::TemplateUnits.collect(registry: registry, buffer: buffer))
+        entry = units[file]
+        return [units, entry] if entry
+
+        # A template the plugin DECLINED is not a unit, and is probed as the command always probed it —
+        # which for a template that is not Ruby is a Prism error about bytes the user did not write, so
+        # the decline is stated first rather than left to be inferred from the error.
+        failures = template_failures(units, file)
+        if failures.empty?
+          @err.puts("type-of: #{file}: plugin declined the template; probing its bytes as Ruby")
+          return nil
+        end
+
+        failures.each do |failure|
+          @err.puts("type-of: #{file}: plugin #{failure.plugin_id} could not compile the template: " \
+                    "#{failure.message}")
+        end
+        1
+      end
+
+      # Only a claimed path builds the index — a `.rb` probe pays no glob expansion and no transform.
+      def template_claimed?(registry, file)
+        return false if registry.nil? || registry.empty?
+
+        relative = Analysis::TemplateUnitPaths.relative(file, Dir.pwd)
+        registry.plugins.any? do |plugin|
+          globs = begin
+            plugin.manifest.template_globs
+          rescue StandardError
+            []
+          end
+          !globs.empty? && Analysis::TemplateUnitPaths.claims?(globs, relative)
+        end
+      end
+
+      def template_failures(units, file)
+        relative = Analysis::TemplateUnitPaths.relative(file, Dir.pwd)
+        units.failures.select { |failure| failure.path == relative }
+      end
+
+      # Every result for one template: the compiled source parsed and indexed once under the unit's seeded
+      # scope, then each requested template position resolved through the inverse map.
+      def resolve_template(file, physical, unit_probe, indexed_targets, context)
+        units, entry = unit_probe
+        parse_result = Prism.parse(entry.source, filepath: file, version: context[:configuration].target_ruby,
+                                                 scopes: units.parse_scopes(file))
+        return 1 if compiled_parse_errors?(parse_result, file, entry)
+
+        scope = units.seed(context[:base_scope].with_source_path(file), file)
+        scope_index = Inference::ScopeIndexer.index(parse_result.value, default_scope: scope)
+        positions = Analysis::TemplateUnitPositions.new(
+          entry: entry, template: File.binread(physical), root: parse_result.value,
+          skip_node_types: Inference::PrecisionScanner::NON_EXPRESSION_NODE_TYPES
+        )
+        probe = { file: file, entry: entry, positions: positions, scope_index: scope_index,
+                  options: context[:options] }
+        indexed_targets.map do |target, index|
+          resolved = resolve_template_target(probe, target)
+          return resolved if resolved.is_a?(Integer)
+
+          [index, resolved]
+        end
+      end
+
+      def resolve_template_target(probe, target)
+        file = probe[:file]
+        positions = probe[:positions]
+        return CLI::EXIT_USAGE unless template_position_in_range?(positions, target)
+        return enumerate_template_line(probe, target.line) if target.column.nil?
+
+        node = positions.node_at(line: target.line, column: target.column)
+        if node.is_a?(Symbol)
+          @err.puts("type-of: no expression found at #{file}:#{target.line}:#{target.column}: " \
+                    "#{DECLINE_MESSAGES.fetch(node)}")
+          return []
+        end
+
+        [type_result(file, target.line, target.column, node, probe[:scope_index], probe[:options],
+                     location_mapper: template_location_mapper(probe))]
+      end
+
+      def enumerate_template_line(probe, line)
+        unless line.between?(1, probe[:positions].template_line_count)
+          @err.puts("type-of: no expression found on #{probe[:file]}:#{line}")
+          return []
+        end
+
+        rows, total = probe[:positions].line_nodes(line)
+        if rows.empty?
+          @err.puts("type-of: no expression found on #{probe[:file]}:#{line}: no compiled expression maps to " \
+                    "a single column of this line (markup, code the template compiler rewrote, or code " \
+                    "copied to more than one place)")
+          return []
+        end
+
+        enumeration = TypeOfCommand::LineEnumeration.new(total: total, shown: rows.length)
+        mapper = template_location_mapper(probe)
+        rows.map do |column, node|
+          type_result(probe[:file], line, column, node, probe[:scope_index], probe[:options],
+                      enumeration: enumeration, location_mapper: mapper)
+        end
+      end
+
+      # The same range errors, and the same exit status, a `.rb` probe gives — measured against the
+      # TEMPLATE's lines, which are the ones the user named. A bare `FILE:LINE` past the end is "no
+      # expression found", exactly as it is for Ruby.
+      def template_position_in_range?(positions, target)
+        return true if target.column.nil?
+
+        message = if target.line < 1 then "line must be >= 1, got #{target.line}"
+                  elsif target.column < 1 then "column must be >= 1, got #{target.column}"
+                  elsif target.line > positions.template_line_count
+                    "line #{target.line} is past the end of the source buffer"
+                  end
+        return true if message.nil?
+
+        @err.puts("type-of: #{message}")
+        false
+      end
+
+      # A `--trace` fallback carries a COMPILED location; it is reported at the template line, and at a
+      # template column only when the location lies in a verbatim run.
+      def template_location_mapper(probe)
+        entry = probe[:entry]
+        positions = probe[:positions]
+        lambda do |location|
+          [entry.template_line(location.start_line), positions.template_column_for(location)]
+        end
+      end
+
+      # A compiled source that does not parse is the plugin's output, not the user's text; its errors are
+      # reported at the template lines they map to, as `rigor check` reports every other finding in a unit.
+      def compiled_parse_errors?(result, file, entry)
+        return false if result.errors.empty?
+
+        result.errors.each do |error|
+          @err.puts("#{file}:#{entry.template_line(error.location.start_line)}: " \
+                    "compiled template does not parse: #{error.message}")
+        end
+        true
+      end
+    end
+  end
+end

data/lib/rigor/cli.rb

@@ -183,7 +183,7 @@ module Rigor
         return 1
       end
 
-      File.write(path, init_template)
+      File.write(path, init_template(path))
       @out.puts("Created #{path}")
       print_init_next_steps(path)
       0
@@ -230,7 +230,7 @@ module Rigor
     # Renders the starter `.rigor.yml` body. The template serialises `Configuration::DEFAULTS` (so the on-disk file
     # round-trips through `Configuration.load`) and prepends a short header that points the user at the keys they are
     # most likely to want to edit.
-    def init_template
+    def init_template(path = ".rigor.dist.yml")
       <<~YAML
         # yaml-language-server: $schema=#{CONFIG_SCHEMA_URL}
         # Rigor configuration. The full key reference is
@@ -266,6 +266,12 @@ module Rigor
         #                Leave unset (or `null`) to auto-detect
         #                `<root>/sig`. Use `[]` to disable
         #                project-RBS loading entirely.
+        # - test_paths:  the directories holding your tests.
+        #                `rigor sig-gen --params=observed` reads
+        #                their call sites to type parameters.
+        #                `rigor init` writes the spec/ and test/
+        #                it finds; unset auto-detects them, and
+        #                `[]` declares the project has none.
         # - cache.path:  where Rigor will eventually persist
         #                analysis results across runs.
         #
@@ -275,10 +281,22 @@ module Rigor
         # tempfile, uri, logger, date, prism, rbs). Adding a
         # `sig/<gem>.rbs` file under `sig/` is the simplest way
         # to extend type coverage today.
-        #{YAML.dump(Configuration::DEFAULTS).sub(/\A---\n/, '')}
+        #{YAML.dump(init_settings(path)).sub(/\A---\n/, '')}
       YAML
     end
 
+    # The settings `rigor init` writes: the defaults, with `test_paths:` spelled out as the test roots found now, so
+    # the project's config says where its tests are rather than leaving it to auto-detection. The roots are written
+    # relative to the config file's directory, which is what {Configuration.load} resolves them against.
+    def init_settings(path)
+      test_paths = Configuration.new.resolved_test_paths
+      return Configuration::DEFAULTS if test_paths.empty?
+
+      config_dir = Pathname(File.expand_path(File.dirname(path)))
+      relative = test_paths.map { |root| Pathname(root).relative_path_from(config_dir).to_s }
+      Configuration::DEFAULTS.merge("test_paths" => relative)
+    end
+
     def run_annotate
       require_relative "cli/annotate_command"
 

data/lib/rigor/configuration/severity_profile.rb

@@ -54,6 +54,11 @@ module Rigor
           "def.override-return-widened" => :off,
           "def.override-param-narrowed" => :off,
           "def.ivar-write-mismatch" => :warning,
+          # Issue #1367 — both report a write its setter rejects, so it raises on every run. The type check rests on
+          # an inferred value type, so it follows `call.argument-type-mismatch` (warning under lenient); the
+          # read-only write needs no type at all, so it is an error in every profile.
+          "global.write-type-mismatch" => :warning,
+          "global.readonly-write" => :error,
           # ADR-8 companion (PHPStan IgnoreParseErrorRule-modelled): a broken suppression comment is
           # equally bad in every profile — it silently fails to do what the author believes it does — so
           # both rules stay :warning across all three profiles (including strict).
@@ -80,7 +85,12 @@ module Rigor
           # Opt-in author assertion: you only see it if you wrote a
           # `conforms-to` directive, so it stays a :warning even in
           # lenient — it is never unsolicited noise.
-          "rbs_extended.unsatisfied-conformance" => :warning
+          "rbs_extended.unsatisfied-conformance" => :warning,
+          # ADR-112 WD5 / #1075 — an error in every profile, lenient included. The rule guards its
+          # false-positive rate through its narrow definition of a contradiction, and ADR-112 WD5 rules
+          # out lowering the severity instead; only a proven disagreement between two declarations the
+          # project wrote itself can fire.
+          "rbs.contradicting-signature" => :error
         }.freeze,
         balanced: {
           "call.undefined-method" => :error,
@@ -110,6 +120,8 @@ module Rigor
           "def.override-return-widened" => :warning,
           "def.override-param-narrowed" => :warning,
           "def.ivar-write-mismatch" => :warning,
+          "global.write-type-mismatch" => :error,
+          "global.readonly-write" => :error,
           "suppression.unknown-rule" => :warning,
           "suppression.empty" => :warning,
           "suppression.unknown-marker" => :warning,
@@ -118,7 +130,8 @@ module Rigor
           "effect.liskov-widened" => :warning,
           "effect.unknown-label" => :info,
           "effect.annotations-unchecked" => :info,
-          "rbs_extended.unsatisfied-conformance" => :warning
+          "rbs_extended.unsatisfied-conformance" => :warning,
+          "rbs.contradicting-signature" => :error
         }.freeze,
         strict: {
           "call.undefined-method" => :error,
@@ -147,6 +160,8 @@ module Rigor
           "def.override-return-widened" => :error,
           "def.override-param-narrowed" => :error,
           "def.ivar-write-mismatch" => :error,
+          "global.write-type-mismatch" => :error,
+          "global.readonly-write" => :error,
           "suppression.unknown-rule" => :warning,
           "suppression.empty" => :warning,
           "suppression.unknown-marker" => :warning,
@@ -158,7 +173,8 @@ module Rigor
           # `:info` even under strict: a residual that failed a build would punish the project for
           # carrying an annotation it has not opted into checking, which is the opposite of the point.
           "effect.annotations-unchecked" => :info,
-          "rbs_extended.unsatisfied-conformance" => :error
+          "rbs_extended.unsatisfied-conformance" => :error,
+          "rbs.contradicting-signature" => :error
         }.freeze
       }.freeze
 

data/lib/rigor/configuration.rb

@@ -49,6 +49,9 @@ module Rigor
       **/node_modules/**
     ].freeze
 
+    # The conventional test roots `test_paths: nil` auto-detects, in this order.
+    CONVENTIONAL_TEST_PATHS = %w[spec test].freeze
+
     DEFAULTS = {
       "target_ruby" => "4.0",
       "paths" => ["lib"],
@@ -57,6 +60,20 @@ module Rigor
       "disable" => [],
       "libraries" => [],
       "signature_paths" => nil,
+      # The project's test roots: the directories (or files) holding its tests. `nil` (the default) auto-detects
+      # whichever of `spec/` and `test/` exist, the same way `signature_paths: nil` auto-detects `sig/`; `[]`
+      # declares that the project has none. `rigor sig-gen --params=observed` harvests call-site observations
+      # from them when no `--observe=PATH` is given. See {#resolved_test_paths}.
+      "test_paths" => nil,
+      # ADR-112 WD4 — `rigor sig-gen` settings. `inline_declared:` decides what happens to a method the inline
+      # reader (`rigor-rbs-inline`) already declares from `# @rbs` / `#:`. `write` (the default) copies the
+      # inline declaration into `sig/`, so the generated signature is the complete contract a gem ships;
+      # `skip` leaves every member that reader declares out of `sig/`, for a project whose Steep reads the
+      # same annotations (`inline: true` beside `signature "sig"`), where the copy would be a second
+      # declaration of one method (`DuplicatedMethodDefinition`). See {#sig_gen_inline_declared}.
+      "sig_gen" => {
+        "inline_declared" => "write"
+      },
       # ADR-17 — project-side monkey-patch pre-evaluation. Empty by default; users opt in by listing explicit
       # files that the analyzer walks before per-file inference so patched-method declarations are visible
       # across the project (e.g. `lib/core_ext/string_extensions.rb`). Slice 1 plumbing only — listed files
@@ -202,11 +219,12 @@ module Rigor
         "auto_detect" => true
       }
     }.freeze
+    Ractor.make_shareable(DEFAULTS)
 
     # Top-level keys whose values are file/directory paths that MUST be resolved relative to the config
     # file's directory. `exclude:` is intentionally NOT in this list — its entries are glob patterns
     # (`**/vendor/**`), not paths.
-    PATH_KEYS = %w[paths signature_paths pre_eval].freeze
+    PATH_KEYS = %w[paths signature_paths test_paths pre_eval].freeze
     private_constant :PATH_KEYS
 
     # Top-level keys this implementation DECLARES but never reads — see `docs/internal-spec/config.md`
@@ -251,7 +269,7 @@ module Rigor
 
     attr_reader :target_ruby, :paths, :exclude_patterns, :plugins, :cache_path, :cache_max_bytes,
                 :cache_validation, :disabled_rules,
-                :libraries, :signature_paths, :fold_platform_specific_paths, :parameter_inference,
+                :libraries, :signature_paths, :test_paths, :fold_platform_specific_paths, :parameter_inference,
                 :plugins_isolation,
                 :plugins_io_network, :plugins_io_allowed_paths,
                 :plugins_io_allowed_url_hosts,
@@ -260,7 +278,7 @@ module Rigor
                 :dependencies, :parallel_workers,
                 :bundler_bundle_path, :bundler_auto_detect, :bundler_lockfile,
                 :rbs_collection_lockfile, :rbs_collection_auto_detect,
-                :pre_eval, :baseline_path, :effects,
+                :pre_eval, :baseline_path, :effects, :sig_gen_inline_declared,
                 :effects_snapshot_path, :effects_snapshot_reach, :effects_snapshot_gate, :effects_tolerated,
                 :effects_labels, :effects_attribution, :effects_envelopes
 
@@ -282,6 +300,16 @@ module Rigor
       @effects_check
     end
 
+    # The test roots a run uses: the declared `test_paths:` as written (already resolved against the
+    # config file's directory by {.load}), or — when the key is unset — whichever of
+    # {CONVENTIONAL_TEST_PATHS} is a directory under `root`, as absolute paths. `root` is the directory
+    # the run treats as the project root (the CLI's CWD), as for `signature_paths:` auto-detection.
+    def resolved_test_paths(root: Dir.pwd)
+      return test_paths unless test_paths.nil?
+
+      CONVENTIONAL_TEST_PATHS.map { |dir| File.expand_path(dir, root) }.select { |dir| File.directory?(dir) }
+    end
+
     # Loads a configuration file.
     #
     # `path == nil` triggers auto-discovery against {DISCOVERY_ORDER}. The first present file in that list is
@@ -509,6 +537,9 @@ module Rigor
       @libraries = Array(data.fetch("libraries", DEFAULTS.fetch("libraries"))).map(&:to_s).freeze
       sig_paths = data.fetch("signature_paths", DEFAULTS.fetch("signature_paths"))
       @signature_paths = sig_paths.nil? ? nil : Array(sig_paths).map(&:to_s).freeze
+      test_paths = data.fetch("test_paths", DEFAULTS.fetch("test_paths"))
+      @test_paths = test_paths.nil? ? nil : Array(test_paths).map(&:to_s).freeze
+      @sig_gen_inline_declared = coerce_sig_gen_inline_declared(data.fetch("sig_gen", nil))
       @pre_eval = expand_pre_eval_entries(
         Array(data.fetch("pre_eval", DEFAULTS.fetch("pre_eval"))).map(&:to_s)
       )
@@ -593,6 +624,9 @@ module Rigor
         "disable" => disabled_rules,
         "libraries" => libraries,
         "signature_paths" => signature_paths,
+        # `test_paths:` is deliberately absent, as `effects:` is: `to_h` feeds the run cache key and the
+        # incremental-snapshot fingerprint, and the test roots change no diagnostic, so editing them must not
+        # invalidate either. `sig_gen:` is absent for the same reason: only `rigor sig-gen` reads it.
         "pre_eval" => pre_eval,
         "fold_platform_specific_paths" => fold_platform_specific_paths,
         "parameter_inference" => parameter_inference,
@@ -980,6 +1014,35 @@ module Rigor
     VALID_CACHE_VALIDATIONS = %w[auto stat digest].freeze
     private_constant :VALID_CACHE_VALIDATIONS
 
+    # The `sig_gen.inline_declared:` values, as the Symbols {#sig_gen_inline_declared} answers.
+    VALID_SIG_GEN_INLINE_DECLARED = %w[write skip].freeze
+    private_constant :VALID_SIG_GEN_INLINE_DECLARED
+
+    # Rejects rather than fails soft: an unrecognised value read as `write` would put a second declaration of
+    # every inline-annotated method into `sig/` for exactly the project that asked for none. A `sig_gen:`
+    # block that omits the key, or is written empty, keeps the default.
+    def coerce_sig_gen_inline_declared(section)
+      section = {} if section.nil?
+      raise ConfigurationError, "sig_gen must be a mapping, got #{section.inspect}" unless section.is_a?(Hash)
+
+      # The schema closes this object (`additionalProperties: false`); a misspelled key here would otherwise
+      # load as the default and write exactly what `inline_declare: skip` was meant to prevent.
+      unknown = section.keys.map(&:to_s) - DEFAULTS.fetch("sig_gen").keys
+      unless unknown.empty?
+        raise ConfigurationError,
+              "sig_gen has unknown key(s) #{unknown.inspect}; known keys: #{DEFAULTS.fetch('sig_gen').keys.inspect}"
+      end
+
+      value = section.fetch("inline_declared", DEFAULTS.dig("sig_gen", "inline_declared")).to_s
+      unless VALID_SIG_GEN_INLINE_DECLARED.include?(value)
+        raise ConfigurationError,
+              "sig_gen.inline_declared must be one of #{VALID_SIG_GEN_INLINE_DECLARED.inspect}, " \
+              "got #{section['inline_declared'].inspect}"
+      end
+
+      value.to_sym
+    end
+
     def coerce_cache_validation(value)
       str = value.to_s
       VALID_CACHE_VALIDATIONS.include?(str) ? str : "auto"