rigortype 0.1.0 → 0.1.2

data/lib/rigor/analysis/rule_catalog.rb

@@ -0,0 +1,343 @@
+# frozen_string_literal: true
+
+require_relative "check_rules"
+
+module Rigor
+  module Analysis
+    # Single-source-of-truth metadata table for every CheckRule
+    # the analyzer ships. Consumed by `rigor explain <rule>` so
+    # users can read the same information the docs site eventually
+    # publishes without leaving the terminal.
+    #
+    # Each entry carries:
+    #
+    # - `id` — canonical rule id (`call.undefined-method`).
+    # - `summary` — single-line headline (≤ 80 chars).
+    # - `fires_when` — bullet-shaped list of conditions that
+    #   trigger the rule, in the order a reader can scan
+    #   top-to-bottom.
+    # - `does_not_fire_when` — explicit list of cases the rule
+    #   intentionally skips. Useful for "why am I NOT seeing
+    #   this diagnostic?" questions.
+    # - `suppression` — short note on how to suppress (in-source
+    #   `# rigor:disable` and the v0.1.2 file-scope variant
+    #   `# rigor:disable-file`, plus `.rigor.yml` `disable:`,
+    #   apply to every rule, so the note covers any rule-specific
+    #   nuance — e.g. unreachable-branch lives on the dead-branch
+    #   line, not the predicate line).
+    # - `severity_authored` — Symbol the rule emits with.
+    # - `severity_by_profile` — Hash of `:lenient` / `:balanced`
+    #   / `:strict` to the configured severity per profile, taken
+    #   from `Configuration::SeverityProfile::PROFILES`.
+    # - `since` — first version the rule shipped in.
+    module RuleCatalog # rubocop:disable Metrics/ModuleLength
+      Entry = Data.define(:id, :summary, :fires_when, :does_not_fire_when,
+                          :suppression, :severity_authored, :severity_by_profile, :since) do
+        def aliases
+          CheckRules::LEGACY_RULE_ALIASES.select { |_legacy, canonical| canonical == id }.keys
+        end
+
+        # Hash-shaped form for `--format=json` consumers. Keys are
+        # Strings so the payload is JSON-stable without a transform
+        # pass.
+        def to_h
+          {
+            "id" => id,
+            "aliases" => aliases,
+            "summary" => summary,
+            "fires_when" => fires_when,
+            "does_not_fire_when" => does_not_fire_when,
+            "suppression" => suppression,
+            "severity_authored" => severity_authored.to_s,
+            "severity_by_profile" => severity_by_profile.transform_keys(&:to_s).transform_values(&:to_s),
+            "since" => since
+          }
+        end
+      end
+
+      ENTRIES = {
+        CheckRules::RULE_UNDEFINED_METHOD => Entry.new(
+          id: CheckRules::RULE_UNDEFINED_METHOD,
+          summary: "Method does not exist on the receiver's statically-known class.",
+          fires_when: [
+            "The call is `receiver.method(...)` with an explicit receiver.",
+            "The receiver type resolves to `Type::Nominal` / `Singleton` / `Constant` / `Tuple` / `HashShape`.",
+            "The receiver class is RBS-known (declared in the loaded environment).",
+            "The user has not declared the method via `def` or recognised `define_method`.",
+            "Neither the receiver class nor an ancestor's RBS sig declares the method."
+          ],
+          does_not_fire_when: [
+            "Implicit-self calls (no receiver) — too noisy without per-method RBS for every helper.",
+            "Receiver is `Dynamic[T]` / `Top` / `Union` — by definition the method set isn't enumerable.",
+            "Receiver class is in the loader but its RBS definition cannot be built (constant aliases)."
+          ],
+          suppression: "`# rigor:disable call.undefined-method` on the call line, " \
+                       "or `disable: [\"call.undefined-method\"]` in `.rigor.yml`.",
+          severity_authored: :error,
+          severity_by_profile: { lenient: :error, balanced: :error, strict: :error },
+          since: "0.0.1"
+        ),
+
+        CheckRules::RULE_WRONG_ARITY => Entry.new(
+          id: CheckRules::RULE_WRONG_ARITY,
+          summary: "Call's positional argument count is outside the declared overloads' envelope.",
+          fires_when: [
+            "Call is `receiver.method(args...)` with explicit receiver + plain positional args.",
+            "Receiver class is RBS-known and the method has a definition.",
+            "Actual positional count is below the min or above the max across all overloads."
+          ],
+          does_not_fire_when: [
+            "Call uses `*splat`, keyword arguments, block-pass, or forwarded arguments.",
+            "Method declares required keyword arguments (caller must pass kwargs the rule doesn't model).",
+            "Method has a `*rest` positional parameter (max arity is unbounded)."
+          ],
+          suppression: "`# rigor:disable call.wrong-arity`.",
+          severity_authored: :error,
+          severity_by_profile: { lenient: :error, balanced: :error, strict: :error },
+          since: "0.0.1"
+        ),
+
+        CheckRules::RULE_ARGUMENT_TYPE => Entry.new(
+          id: CheckRules::RULE_ARGUMENT_TYPE,
+          summary: "Call passes an argument whose type the parameter cannot accept.",
+          fires_when: [
+            "The parameter type rejects the argument under `accepts(arg, mode: :gradual)`.",
+            "Method has a single overload (multi-overload checking is deferred).",
+            "Both sides have a non-Dynamic concrete type."
+          ],
+          does_not_fire_when: [
+            "Either the parameter or the argument is `Dynamic[T]`.",
+            "Method has multiple overloads.",
+            "Method has `*rest_positionals`, required keywords, or trailing positionals."
+          ],
+          suppression: "`# rigor:disable call.argument-type-mismatch`.",
+          severity_authored: :error,
+          severity_by_profile: { lenient: :warning, balanced: :error, strict: :error },
+          since: "0.0.2"
+        ),
+
+        CheckRules::RULE_NIL_RECEIVER => Entry.new(
+          id: CheckRules::RULE_NIL_RECEIVER,
+          summary: "Receiver may be nil and the method is not defined on NilClass.",
+          fires_when: [
+            "Receiver type is `Type::Union` containing `Constant<nil>` (or `nil` from the RBS Optional).",
+            "The non-nil branch has the method, but `NilClass` does not.",
+            "Call is not safe-navigation (`x&.method`)."
+          ],
+          does_not_fire_when: [
+            "Method exists on every member of the union (including NilClass).",
+            "Receiver was narrowed via `return if x.nil?` / similar early-return guard.",
+            "Call uses safe-navigation (`x&.method`)."
+          ],
+          suppression: "`# rigor:disable call.possible-nil-receiver`.",
+          severity_authored: :error,
+          severity_by_profile: { lenient: :warning, balanced: :error, strict: :error },
+          since: "0.0.2"
+        ),
+
+        CheckRules::RULE_DUMP_TYPE => Entry.new(
+          id: CheckRules::RULE_DUMP_TYPE,
+          summary: "`dump_type(expr)` from Rigor::Testing — informational type print.",
+          fires_when: [
+            "Top-level / DSL-block call to `dump_type(expr)` after `include Rigor::Testing`."
+          ],
+          does_not_fire_when: [
+            "Outside a context that includes Rigor::Testing.",
+            "Argument is not a single expression."
+          ],
+          suppression: "Remove the `dump_type` call (it's a debug helper, not a real diagnostic).",
+          severity_authored: :info,
+          severity_by_profile: { lenient: :info, balanced: :info, strict: :error },
+          since: "0.0.1"
+        ),
+
+        CheckRules::RULE_ASSERT_TYPE => Entry.new(
+          id: CheckRules::RULE_ASSERT_TYPE,
+          summary: "`assert_type(\"<expected>\", expr)` from Rigor::Testing — type-equality check.",
+          fires_when: [
+            "Inferred type's display does not match the asserted string.",
+            "Useful in fixture self-assertions (every `spec/integration/fixtures/*.rb` uses it)."
+          ],
+          does_not_fire_when: [
+            "Inferred type matches the assertion exactly."
+          ],
+          suppression: "Update the assertion to the actual inferred type, or correct the source.",
+          severity_authored: :error,
+          severity_by_profile: { lenient: :error, balanced: :error, strict: :error },
+          since: "0.0.1"
+        ),
+
+        CheckRules::RULE_ALWAYS_RAISES => Entry.new(
+          id: CheckRules::RULE_ALWAYS_RAISES,
+          summary: "Call provably raises (today: Integer division-by-zero).",
+          fires_when: [
+            "Receiver is `Integer` / `IntegerRange` / `Constant<Integer>`.",
+            "Operator is `/` / `%` / `div` / `modulo` / `divmod`.",
+            "Argument is a `Constant<Integer>` whose value is exactly zero."
+          ],
+          does_not_fire_when: [
+            "Receiver is Float / Rational (those return Infinity / NaN, not an exception).",
+            "Argument is a Union containing zero (\"may raise\" not \"always raises\")."
+          ],
+          suppression: "`# rigor:disable flow.always-raises`.",
+          severity_authored: :error,
+          severity_by_profile: { lenient: :warning, balanced: :error, strict: :error },
+          since: "0.0.3"
+        ),
+
+        CheckRules::RULE_UNREACHABLE_BRANCH => Entry.new(
+          id: CheckRules::RULE_UNREACHABLE_BRANCH,
+          summary: "An if / unless / ternary's literal predicate makes one branch dead.",
+          fires_when: [
+            "Predicate is a syntactic literal: `true` / `false` / `nil` / Integer / Float / String / Symbol / Regexp.",
+            "The corresponding dead branch carries a non-empty body."
+          ],
+          does_not_fire_when: [
+            "Predicate is an inferred-constant expression (not a literal). The literal-only envelope avoids " \
+            "false positives from Rigor's incomplete loop / mutation / RBS-strictness modelling.",
+            "The dead branch is empty (no useful location to point at)."
+          ],
+          suppression: "`# rigor:disable unreachable-branch` on the dead-branch line (the diagnostic " \
+                       "points at the dead branch, not the predicate, so the suppression goes there).",
+          severity_authored: :warning,
+          severity_by_profile: { lenient: :info, balanced: :warning, strict: :error },
+          since: "0.1.2"
+        ),
+
+        CheckRules::RULE_ALWAYS_TRUTHY_CONDITION => Entry.new(
+          id: CheckRules::RULE_ALWAYS_TRUTHY_CONDITION,
+          summary: "An if / unless / ternary predicate's inferred type folds to a constant.",
+          fires_when: [
+            "Predicate's inferred type is `Type::Constant<true | false | nil | ...>`.",
+            "Predicate is NOT a syntactic literal (the literal-only `flow.unreachable-branch` rule covers those)."
+          ],
+          does_not_fire_when: [
+            "Predicate sits inside a `WhileNode` / `UntilNode` / `ForNode` / `BlockNode` ancestor — " \
+            "Rigor's mutation tracking through loop bodies is incomplete enough that an inferred " \
+            "`Constant<bool>` can be a false positive.",
+            "Predicate is a defensive `.nil?` / `.empty?` / `.zero?` / `.any?` / `.none?` / `.all?` / " \
+            "`.respond_to?` call — these typically fire when the user is being more cautious than the " \
+            "RBS strict-on-returns sig admits.",
+            "Predicate folds to a non-Constant type (Union / Nominal / Dynamic / etc.)."
+          ],
+          suppression: "`# rigor:disable always-truthy-condition` on the predicate line.",
+          severity_authored: :warning,
+          severity_by_profile: { lenient: :info, balanced: :warning, strict: :error },
+          since: "0.1.2"
+        ),
+
+        CheckRules::RULE_DEAD_ASSIGNMENT => Entry.new(
+          id: CheckRules::RULE_DEAD_ASSIGNMENT,
+          summary: "Local variable assigned in a method body but never read.",
+          fires_when: [
+            "Plain `LocalVariableWriteNode` (not `+=` / `||=` / multi-assign) inside a `DefNode` body.",
+            "The target name does not appear as a `LocalVariableReadNode` anywhere in the same body, " \
+            "including nested blocks / lambdas.",
+            "The write is not the last statement of the body (Ruby's implicit return)."
+          ],
+          does_not_fire_when: [
+            "Top-level / class-body assignments (their reachability spans the file's introspection / require surface).",
+            "The target name starts with `_` (Ruby convention for intentionally-unused).",
+            "The write is a destructure (`a, b = foo`) or operator-write (`x += 1` / `x ||= 1`).",
+            "The write is the last statement of the method body (assignments return their rvalue)."
+          ],
+          suppression: "`# rigor:disable dead-assignment` on the offending line, or rename the local to `_<name>`.",
+          severity_authored: :warning,
+          severity_by_profile: { lenient: :info, balanced: :warning, strict: :error },
+          since: "0.1.2"
+        ),
+
+        CheckRules::RULE_RETURN_TYPE => Entry.new(
+          id: CheckRules::RULE_RETURN_TYPE,
+          summary: "Method body's last-expression type is incompatible with the declared return type.",
+          fires_when: [
+            "Method has a `def` body the engine can re-type.",
+            "Method's RBS sig declares a non-`untyped` return type.",
+            "Body's inferred return type does not flow into the declared type under gradual acceptance.",
+            "When the RBS sig carries `%a{rigor:v1:return: <refinement>}` (v0.1.2), the refinement " \
+            "carrier — `non-empty-string`, `positive-int`, etc. — replaces the bare RBS class for the " \
+            "comparison, so a body the bare class would accept may still fail the refinement."
+          ],
+          does_not_fire_when: [
+            "Method's declared return is `untyped` / `void`.",
+            "Body's last expression is `Dynamic[T]` (the engine cannot rule out the declared type)."
+          ],
+          suppression: "`# rigor:disable def.return-type-mismatch`.",
+          severity_authored: :warning,
+          severity_by_profile: { lenient: :warning, balanced: :warning, strict: :error },
+          since: "0.1.0"
+        ),
+
+        CheckRules::RULE_VISIBILITY_MISMATCH => Entry.new(
+          id: CheckRules::RULE_VISIBILITY_MISMATCH,
+          summary: "Explicit-receiver call to a method declared `private` in source.",
+          fires_when: [
+            "Call is `receiver.method(...)` with explicit non-self receiver.",
+            "Receiver type resolves to `Type::Nominal[X]`.",
+            "X is a user-defined class whose source carries the method under `private`."
+          ],
+          does_not_fire_when: [
+            "Implicit-self call (no receiver) — always allowed for private.",
+            "Receiver is `self` (Ruby 2.7+ permits `self.private_method`).",
+            "Receiver class is RBS-known but not user-source-defined (RBS-side visibility is deferred).",
+            "Method is `:protected` (subclass tracking is deferred)."
+          ],
+          suppression: "`# rigor:disable method-visibility-mismatch`.",
+          severity_authored: :error,
+          severity_by_profile: { lenient: :warning, balanced: :error, strict: :error },
+          since: "0.1.2"
+        ),
+
+        CheckRules::RULE_IVAR_WRITE_MISMATCH => Entry.new(
+          id: CheckRules::RULE_IVAR_WRITE_MISMATCH,
+          summary: "Same instance variable assigned a different concrete class within one class.",
+          fires_when: [
+            "Two or more `@var = ...` writes occur in instance methods of the same class.",
+            "First write's rvalue resolves to a concrete class (Nominal / Singleton / Constant / Tuple → " \
+            "\"Array\" / HashShape → \"Hash\").",
+            "A later write's rvalue resolves to a different concrete class."
+          ],
+          does_not_fire_when: [
+            "Later write is `nil` — the `@cache = nil` clear-idiom is allowlisted.",
+            "Either side is Union / Dynamic / IntegerRange / a shape-varied carrier.",
+            "Writes live in different classes that happen to share an ivar name.",
+            "Writes are in `def self.foo` (singleton) bodies — those track separately."
+          ],
+          suppression: "`# rigor:disable ivar-write-mismatch` on the offending write.",
+          severity_authored: :error,
+          severity_by_profile: { lenient: :warning, balanced: :warning, strict: :error },
+          since: "0.1.2"
+        )
+      }.freeze
+
+      module_function
+
+      # Looks up a rule by canonical id, legacy alias, or family
+      # wildcard. Returns an Array<Entry>:
+      #
+      # - canonical id → 1-element array,
+      # - legacy alias → 1-element array (resolved to canonical),
+      # - family token (`call`) → every entry under that family,
+      # - unknown token → empty array.
+      def resolve(token)
+        token = token.to_s
+        return [ENTRIES.fetch(token)] if ENTRIES.key?(token)
+
+        if CheckRules::LEGACY_RULE_ALIASES.key?(token)
+          canonical = CheckRules::LEGACY_RULE_ALIASES.fetch(token)
+          return [ENTRIES.fetch(canonical)]
+        end
+
+        if CheckRules::RULE_FAMILIES.include?(token)
+          return ENTRIES.values.select { |entry| entry.id.start_with?("#{token}.") }.sort_by(&:id)
+        end
+
+        []
+      end
+
+      def all
+        ENTRIES.values.sort_by(&:id)
+      end
+    end
+  end
+end

data/lib/rigor/analysis/runner.rb

@@ -54,22 +54,45 @@ module Rigor
         Inference::MethodDispatcher::FileFolding.fold_platform_specific_paths =
           @configuration.fold_platform_specific_paths
 
+        target_ruby_error = validate_target_ruby
+        return Result.new(diagnostics: [target_ruby_error]) if target_ruby_error
+
+        @plugin_registry = load_plugins
         environment = Environment.for_project(
           libraries: @configuration.libraries,
           signature_paths: @configuration.signature_paths,
-          cache_store: @cache_store
+          cache_store: @cache_store,
+          plugin_registry: @plugin_registry
         )
-
-        @plugin_registry = load_plugins
         expansion = expand_paths(paths)
 
         diagnostics = plugin_load_diagnostics
+        diagnostics += plugin_prepare_diagnostics
         diagnostics += expansion.fetch(:errors)
         diagnostics += expansion.fetch(:files).flat_map { |path| analyze_file(path, environment) }
 
         Result.new(diagnostics: apply_severity_profile(diagnostics))
       end
 
+      # `target_ruby` flows through to Prism's `version:` option.
+      # Prism enforces the supported range and raises
+      # `ArgumentError` for versions it does not recognise. Run a
+      # one-time smoke parse here so a misconfigured target_ruby
+      # surfaces as a single project-level diagnostic instead of
+      # crashing the whole run on the first file.
+      def validate_target_ruby
+        Prism.parse("nil", version: @configuration.target_ruby)
+        nil
+      rescue ArgumentError => e
+        Diagnostic.new(
+          path: ".rigor.yml", line: 1, column: 1,
+          message: "target_ruby #{@configuration.target_ruby.inspect} is not accepted by Prism: #{e.message}",
+          severity: :error,
+          rule: "configuration-error",
+          source_family: :builtin
+        )
+      end
+
       private
 
       # Loads project-configured plugins through {Rigor::Plugin::Loader}
@@ -117,7 +140,8 @@ module Rigor
         Plugin::TrustPolicy.new(
           trusted_gems: trusted_gems,
           allowed_read_roots: roots,
-          network_policy: @configuration.plugins_io_network
+          network_policy: @configuration.plugins_io_network,
+          allowed_url_hosts: @configuration.plugins_io_allowed_url_hosts
         )
       end
 
@@ -183,6 +207,47 @@ module Rigor
         end
       end
 
+      # ADR-9 slice 3 — invokes every loaded plugin's `#prepare`
+      # hook once per run, after the loader's `#init` pass and
+      # before per-file iteration. Plugins publish facts here
+      # for cross-plugin consumption via the shared
+      # `services.fact_store`. Failures isolate as
+      # `:plugin_loader runtime-error` diagnostics, mirroring the
+      # `#diagnostics_for_file` raise envelope in
+      # `plugin_runtime_error_diagnostic`.
+      #
+      # Slice 3 visits plugins in registration order. Slice 5
+      # introduces topological ordering by `manifest(consumes:)`
+      # so producers always run before consumers; until then,
+      # `Configuration#plugins` order MUST be producer-first if
+      # cross-plugin dependencies exist.
+      def plugin_prepare_diagnostics
+        return [] if @plugin_registry.empty?
+
+        @plugin_registry.plugins.flat_map { |plugin| invoke_plugin_prepare(plugin) }
+      end
+
+      def invoke_plugin_prepare(plugin)
+        plugin.prepare(plugin.services)
+        []
+      rescue StandardError => e
+        [plugin_prepare_error_diagnostic(plugin, e)]
+      end
+
+      def plugin_prepare_error_diagnostic(plugin, error)
+        plugin_id = safe_plugin_id(plugin)
+        Diagnostic.new(
+          path: ".rigor.yml",
+          line: 1,
+          column: 1,
+          message: "plugin #{plugin_id.inspect} raised during prepare: " \
+                   "#{error.class}: #{error.message}",
+          severity: :error,
+          rule: "runtime-error",
+          source_family: :plugin_loader
+        )
+      end
+
       # ADR-7 § "Slice 5-A/5-B" — invokes every loaded plugin's
       # per-file diagnostic emission hook
       # (`Plugin::Base#diagnostics_for_file`) and re-stamps the
@@ -254,7 +319,7 @@ module Rigor
         errors = []
         Array(paths).each do |path|
           if File.directory?(path)
-            files.concat(Dir.glob(File.join(path, RUBY_GLOB)))
+            files.concat(reject_excluded(Dir.glob(File.join(path, RUBY_GLOB))))
           elsif File.file?(path) && path.end_with?(".rb")
             files << path
           elsif File.exist?(path)
@@ -266,6 +331,25 @@ module Rigor
         { files: files, errors: errors }
       end
 
+      # `Configuration#exclude_patterns` is a list of glob patterns
+      # checked against each globbed path via `File.fnmatch?` (without
+      # `FNM_PATHNAME`, so `**` and `*` both span path separators —
+      # the patterns behave like substring globs). Built-in defaults
+      # exclude `vendor/bundle`, `.bundle`, `node_modules`, and `tmp`
+      # so the analyser never walks into vendored deps or build
+      # artefacts. User-supplied entries (`.rigor.yml` `exclude:`)
+      # layer on top. Explicit file arguments to the CLI bypass this
+      # filter — only the directory-glob expansion is filtered.
+      def reject_excluded(file_list)
+        return file_list if @configuration.exclude_patterns.empty?
+
+        file_list.reject { |path| excluded?(path) }
+      end
+
+      def excluded?(path)
+        @configuration.exclude_patterns.any? { |pattern| File.fnmatch?(pattern, path) }
+      end
+
       def path_error(path, message)
         Diagnostic.new(
           path: path,
@@ -277,7 +361,7 @@ module Rigor
       end
 
       def analyze_file(path, environment) # rubocop:disable Metrics/MethodLength
-        parse_result = Prism.parse_file(path)
+        parse_result = Prism.parse_file(path, version: @configuration.target_ruby)
         return parse_diagnostics(path, parse_result) unless parse_result.errors.empty?
 
         scope = Scope.empty(environment: environment)

data/lib/rigor/builtins/regex_refinement.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require_relative "../type"
+
+module Rigor
+  module Builtins
+    # Maps a curated table of canonical regex sub-patterns onto the
+    # imported refinement carriers Rigor already ships
+    # (`decimal-int-string`, `hex-int-string`, `octal-int-string`,
+    # `lowercase-string`, `uppercase-string`, `numeric-string`).
+    # See `docs/type-specification/imported-built-in-types.md` for
+    # the registry the refinements come from and `docs/MILESTONES.md`
+    # § "v0.1.1 — Planned" Track 1 slice 1 for the binding scope of
+    # this recogniser.
+    #
+    # The intended consumer is `Inference::Narrowing.analyse_match_write`:
+    # given `if /(?<year>\d+)/ =~ str; year; end`, the v0.1.0
+    # baseline narrows `year` to plain `String`; v0.1.1 introspects
+    # the regex source and narrows further to
+    # `decimal-int-string` whenever the named-capture body matches
+    # one of the rows in {RULES}.
+    #
+    # Recognised body shapes (each row admits the `+` quantifier
+    # and the bounded `{n}` / `{n,m}` forms with `n >= 1`):
+    #
+    #   - `\d`                     -> decimal-int-string
+    #   - `\h`                     -> hex-int-string
+    #   - `[0-9a-fA-F]`            -> hex-int-string
+    #   - `[0-9a-f]`, `[0-9A-F]`   -> hex-int-string
+    #   - `[0-7]`                  -> octal-int-string
+    #   - `[a-z]`                  -> lowercase-string
+    #   - `[A-Z]`                  -> uppercase-string
+    #   - `[[:digit:]]`            -> numeric-string
+    #
+    # Anything outside the table returns `nil` so the calling
+    # narrowing site falls back to its previous behaviour
+    # (plain `String`). Arbitrary regex semantic equivalence is
+    # undecidable, so the table is intentionally a small audited
+    # set of canonical shapes rather than a general equivalence
+    # checker.
+    module RegexRefinement
+      # `+` (one-or-more) or `{n}` / `{n,m}` (n >= 1, m >= n).
+      # The bound check is enforced separately by
+      # {valid_bounds?} after the structural match succeeds, so
+      # forms like `\d{0,5}` or `\d{5,3}` reject even though they
+      # parse syntactically.
+      QUANTIFIER_SOURCE = '(?:\+|\{\d+(?:,\d+)?\})'
+      private_constant :QUANTIFIER_SOURCE
+
+      RULES = [
+        [/\A\\d#{QUANTIFIER_SOURCE}\z/, :decimal_int_string],
+        [/\A\\h#{QUANTIFIER_SOURCE}\z/, :hex_int_string],
+        [/\A\[0-9a-fA-F\]#{QUANTIFIER_SOURCE}\z/, :hex_int_string],
+        [/\A\[0-9a-f\]#{QUANTIFIER_SOURCE}\z/, :hex_int_string],
+        [/\A\[0-9A-F\]#{QUANTIFIER_SOURCE}\z/, :hex_int_string],
+        [/\A\[0-7\]#{QUANTIFIER_SOURCE}\z/, :octal_int_string],
+        [/\A\[a-z\]#{QUANTIFIER_SOURCE}\z/, :lowercase_string],
+        [/\A\[A-Z\]#{QUANTIFIER_SOURCE}\z/, :uppercase_string],
+        [/\A\[\[:digit:\]\]#{QUANTIFIER_SOURCE}\z/, :numeric_string]
+      ].freeze
+      private_constant :RULES
+
+      BOUND_RE = /\{(\d+)(?:,(\d+))?\}\z/
+      private_constant :BOUND_RE
+
+      module_function
+
+      # @param body [String, nil] a regex sub-pattern, typically the
+      #   inner body of a `(?<name>body)` named capture. Anchors
+      #   (`\A`, `\z`, `^`, `$`) are not stripped — the recogniser
+      #   table targets bodies that the regex engine treats as
+      #   anchored to the capture group bounds.
+      # @return [Rigor::Type, nil] the matching imported refinement
+      #   carrier, or `nil` if `body` is not a recognised shape.
+      def for_capture_body(body)
+        return nil if body.nil? || body.empty?
+
+        rule = RULES.find { |pattern, _| pattern.match?(body) }
+        return nil if rule.nil?
+        return nil unless valid_bounds?(body)
+
+        Type::Combinator.public_send(rule.last)
+      end
+
+      # Filters the bounded-quantifier forms to ones whose lower
+      # bound is at least 1 and whose upper bound (if any) is at
+      # least the lower bound. Without this, `\d{0,5}` would be
+      # accepted even though it admits the empty string, which is
+      # not a valid `decimal-int-string`.
+      def valid_bounds?(body)
+        m = BOUND_RE.match(body)
+        return true if m.nil?
+
+        low = Integer(m[1])
+        return false if low < 1
+
+        high = m[2] && Integer(m[2])
+        return true if high.nil?
+
+        low <= high
+      end
+    end
+  end
+end