rigortype 0.1.19 → 0.2.0

data/lib/rigor/builtins/predefined_constant_refinements.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require_relative "../type"
+
+module Rigor
+  module Builtins
+    # Refined types for predefined Ruby / stdlib constants whose upstream
+    # RBS signatures are broader than the constants' documented runtime
+    # invariants.
+    #
+    # Resolution is two-tiered:
+    #
+    # **Tier 1 — exact-value whitelist** (`FOLDED_CONSTANTS`):
+    # Constants whose value is bit-for-bit identical across every Ruby
+    # version and platform are folded to `Constant[T]`: the `Math::PI`
+    # / `Math::E` math constants (C's `M_PI` / `M_E`) and the four
+    # IEEE 754 binary64 magnitude constants `Float::INFINITY` /
+    # `::MAX` / `::MIN` / `::EPSILON` (each a single format-mandated bit
+    # pattern). Add new entries only when the value is truly
+    # cross-implementation invariant AND compares reflexively under
+    # `==` — the latter is why `Float::NAN` is deliberately EXCLUDED:
+    # `NaN == NaN` is `false`, so a `Constant[NAN]` would violate the
+    # `Type::Constant` `==` / `eql?` / `hash` contract (it would hash
+    # equal to itself yet compare unequal), corrupting type-equality
+    # and union dedup. The binary64 *integer* shape parameters
+    # (`Float::DIG` / `MANT_DIG` / `MAX_EXP` / …) are intentionally NOT
+    # folded: upstream RBS hedges them as "Usually defaults to …", and
+    # as plain `Integer`s they fall through Tier 2 to the RBS type
+    # harmlessly. `Complex::I` is deferred (no complex-fold consumer).
+    #
+    # **Tier 2 — runtime String inspection**:
+    # For any other constant, the module resolves it via `const_get`
+    # against the analyzer's own Ruby runtime.  Core / stdlib constants
+    # (e.g. `RUBY_VERSION`, `RUBY_PLATFORM`) are always loaded into the
+    # analyzer process; project-defined constants are not (they live only
+    # in ASTs), so their `const_get` raises `NameError` and the lookup
+    # falls through to the RBS type tier.
+    #
+    # For a successfully resolved `String` value:
+    # - empty string  → no refinement (fall through to RBS `String`)
+    # - a Ruby numeric literal  → `numeric-string`
+    # - non-empty otherwise  → `non-empty-string`
+    #
+    # **Exclusion set** (`RUNTIME_INSPECTION_EXCLUDED`):
+    # String constants that appear non-empty in the current runtime but
+    # are documented to be potentially empty in some build configuration
+    # or alternative implementation.  Exclusions are populated by
+    # scanning Ruby's C source (version.c, etc.) and RBS comments for
+    # any constant whose documentation says "may be empty" or
+    # "platform-specific default".  None are known today; the set
+    # exists as a safety net.
+    #
+    # This module is consulted by `Environment#constant_for_name` BEFORE
+    # the RBS constant-type table (widest types) but AFTER in-source
+    # constant writes (the user's own `Math::PI = 0.0` takes precedence
+    # via the lexical-candidate walk in `ExpressionTyper`).
+    module PredefinedConstantRefinements
+      # --- tier 1 -------------------------------------------------------
+
+      # Exact-value fold whitelist.  Keys are unqualified constant paths
+      # (no leading "::") matching what `Environment#constant_for_name`
+      # receives.
+      FOLDED_CONSTANTS = {
+        # Math module — IEEE 754 bit-identical across all MRI / JRuby /
+        # TruffleRuby builds; folding enables precise constant arithmetic.
+        "Math::PI" => Type::Combinator.constant_of(::Math::PI).freeze,
+        "Math::E" => Type::Combinator.constant_of(::Math::E).freeze,
+
+        # Float magnitude limits — each a single format-mandated IEEE 754
+        # binary64 bit pattern (`+Inf`, `DBL_MAX`, `DBL_MIN`,
+        # `DBL_EPSILON`), reflexive under `==`. `Float::NAN` is excluded
+        # (non-reflexive `==` — see the module-level note).
+        "Float::INFINITY" => Type::Combinator.constant_of(::Float::INFINITY).freeze,
+        "Float::MAX" => Type::Combinator.constant_of(::Float::MAX).freeze,
+        "Float::MIN" => Type::Combinator.constant_of(::Float::MIN).freeze,
+        "Float::EPSILON" => Type::Combinator.constant_of(::Float::EPSILON).freeze
+      }.freeze
+      private_constant :FOLDED_CONSTANTS
+
+      # --- tier 2 -------------------------------------------------------
+
+      # String constants whose runtime value is non-empty in the current
+      # Ruby but that should NOT be narrowed because they are documented
+      # to be potentially empty in some build or implementation.
+      #
+      # Methodology: grep Ruby's version.c and similar C sources, and the
+      # RBS comment corpus, for any constant annotated with "may be empty"
+      # or "platform-specific default".  Add the full qualified path
+      # (without leading "::") when a genuine risk is found.
+      RUNTIME_INSPECTION_EXCLUDED = Set[].freeze
+      private_constant :RUNTIME_INSPECTION_EXCLUDED
+
+      NON_EMPTY_STRING = Type::Combinator.non_empty_string.freeze
+      NUMERIC_STRING   = Type::Combinator.numeric_string.freeze
+      private_constant :NON_EMPTY_STRING, :NUMERIC_STRING
+
+      # --- public API ---------------------------------------------------
+
+      # @param name [String] unqualified constant name (e.g. `"Math::PI"`,
+      #   `"RUBY_VERSION"`, `"Ruby::ENGINE"`)
+      # @return [Rigor::Type, nil] refined type, or nil to fall through
+      def self.lookup(name)
+        FOLDED_CONSTANTS[name] || inspect_runtime_string(name)
+      end
+
+      # --- private ------------------------------------------------------
+
+      # Resolves `name` via `const_get` in the analyzer's runtime and
+      # returns a refined String carrier, or nil.
+      def self.inspect_runtime_string(name)
+        return nil if RUNTIME_INSPECTION_EXCLUDED.include?(name)
+
+        mod = ::Object
+        name.split("::").each do |part|
+          # Resolve only constants already present — never let analysing a
+          # reference drive the analyzer's own runtime to autoload or run a
+          # `const_missing` hook. A `Digest::UUID` reference in project code
+          # otherwise makes `const_get` trigger `Digest.const_missing` →
+          # `require "digest/uuid"`, and a missing optional library raises
+          # `LoadError` (a `ScriptError`, not the `NameError` the const_get
+          # walk expects), which would abort the whole run rather than fall
+          # through to the RBS tier. `const_defined?(part, false)` answers
+          # the same "is this resolvable here" question without the side
+          # effect — a project-defined constant (the common case) is simply
+          # absent and returns nil, no exception raised.
+          return nil unless mod.is_a?(::Module) && mod.const_defined?(part, false)
+
+          mod = mod.const_get(part, false)
+        end
+
+        return nil unless mod.is_a?(::String) && !mod.empty?
+
+        classify_string(mod)
+      rescue ::NameError, ::TypeError, ::LoadError
+        nil
+      end
+      private_class_method :inspect_runtime_string
+
+      # @param value [String] a non-empty string
+      # @return [Rigor::Type]
+      def self.classify_string(value)
+        if Type::Refined.ruby_numeric_literal?(value)
+          NUMERIC_STRING
+        else
+          NON_EMPTY_STRING
+        end
+      end
+      private_class_method :classify_string
+    end
+  end
+end

data/lib/rigor/cache/store.rb

@@ -13,9 +13,10 @@ module Rigor
   module Cache
     # Filesystem-backed cache store. Schema, layout, file format,
     # atomicity, and locking are fixed by [ADR-6](../../../docs/adr/6-cache-persistence-backend.md);
-    # callers see the [`Rigor::Cache::Descriptor`](descriptor.rb)
-    # value object plus this class' `#fetch_or_compute` entry point
-    # and nothing else.
+    # callers use `#fetch_or_compute` (producer-keyed),
+    # `#fetch_or_validate` (record-and-validate for discovered-dep
+    # caches, ADR-45), `#stats`, `#evict!`, and `.disk_inventory`,
+    # plus the [`Rigor::Cache::Descriptor`](descriptor.rb) value object.
     #
     # Read failures (missing file, bad magic, format-version mismatch,
     # corrupt SHA-256 trailer, un-inflatable or unmarshal-able payload)
@@ -119,6 +120,7 @@ module Rigor
       #   When the root does not exist or has no schema-version
       #   marker, `schema_version` is nil and the producer list is
       #   empty.
+      #
       # The `schema_version.txt` marker content. Covers BOTH
       # invalidation axes: the descriptor schema and the on-disk byte
       # layout ({FORMAT_VERSION}, ADR-54). A format bump leaves the

data/lib/rigor/cli/annotate_command.rb

@@ -1,10 +1,12 @@
 # frozen_string_literal: true
 
 require "English"
+require "json"
 require "optionparser"
 require "prism"
 
 require_relative "../configuration"
+require_relative "options"
 require_relative "../environment"
 require_relative "../scope"
 require_relative "../inference/def_return_typer"
@@ -37,10 +39,10 @@ module Rigor
       # Trailing `#=> …` annotation comment. Matched and stripped
       # before re-annotating so re-running is idempotent — this
       # follows xmpfilter's convention of owning the `#=>` marker,
-      # and also absorbs the pre-v0.2.0 `#=> dump_type: <type>`
-      # spelling. The leading `\s` requirement keeps a `#=>` inside
-      # a string literal (no preceding whitespace ambiguity aside)
-      # from matching mid-expression.
+      # and also absorbs the older `#=> dump_type: <type>` spelling
+      # (idempotency across re-runs). The leading `\s` requirement
+      # keeps a `#=>` inside a string literal (no preceding
+      # whitespace ambiguity aside) from matching mid-expression.
       ANNOTATION_PATTERN = /\s+#=>(?:\s.*)?\z/
 
       # Arguments for highlighting through `bat`: the annotated
@@ -71,11 +73,15 @@ module Rigor
       def parse_options
         # Default: colour a tty, unless `NO_COLOR` opts out. An
         # explicit `--color` / `--no-color` overrides both.
-        options = { config: nil, color: @out.tty? && !no_color_env?, bat: nil }
+        options = { config: nil, color: @out.tty? && !no_color_env?, bat: nil, format: :text }
 
         parser = OptionParser.new do |opts|
           opts.banner = USAGE
-          opts.on("--config=PATH", "Path to the Rigor configuration file") { |value| options[:config] = value }
+          Options.add_config(opts, options)
+          opts.on("--format=FORMAT", %w[text json],
+                  "Output format: text (default) or json (a { line => type } map)") do |value|
+            options[:format] = value.to_sym
+          end
           opts.on("--[no-]color",
                   "Force or disable ANSI colour (default: auto-detect a tty; honours NO_COLOR)") do |value|
             options[:color] = value
@@ -122,10 +128,25 @@ module Rigor
         )
         line_types = LineTypeCollector.new(scope_index).collect(parse_result.value)
 
-        @out.puts(render(annotate(source, line_types), color: options.fetch(:color), bat: options.fetch(:bat)))
+        case options.fetch(:format)
+        when :json
+          emit_json(line_types)
+        else
+          @out.puts(render(annotate(source, line_types), color: options.fetch(:color), bat: options.fetch(:bat)))
+        end
         0
       end
 
+      # `--format json` — emit the { line_number => type } map directly, the
+      # same data the text renderer consumes, so clients (the playground,
+      # editors) get structured annotations without reparsing the `#=> <type>`
+      # comment grammar. Values are the short type descriptions the text form
+      # also shows; keys are 1-based line numbers as strings (JSON object keys).
+      def emit_json(line_types)
+        annotations = line_types.keys.sort.to_h { |line| [line.to_s, line_types[line].describe(:short)] }
+        @out.puts(JSON.generate({ "annotations" => annotations }))
+      end
+
       def base_scope(configuration)
         Scope.empty(
           environment: Environment.for_project(

data/lib/rigor/cli/baseline_command.rb

@@ -3,6 +3,7 @@
 require "optparse"
 
 require_relative "../analysis/baseline"
+require_relative "options"
 require_relative "../analysis/runner"
 require_relative "../cache/store"
 require_relative "../configuration"
@@ -106,7 +107,7 @@ module Rigor
         }
         parser = OptionParser.new do |opts|
           opts.banner = "Usage: rigor baseline #{subcommand} [options]"
-          opts.on("--config=PATH", "Path to the Rigor configuration file") { |v| options[:config] = v }
+          Options.add_config(opts, options)
           opts.on("--output=PATH", "Write baseline to PATH (default: #{DEFAULT_BASELINE_PATH})") do |v|
             options[:output] = v
           end
@@ -270,7 +271,7 @@ module Rigor
         }
         parser = OptionParser.new do |opts|
           opts.banner = "Usage: rigor baseline drift [options]"
-          opts.on("--config=PATH", "Path to the Rigor configuration file") { |v| options[:config] = v }
+          Options.add_config(opts, options)
           opts.on("--baseline=PATH", "Path to the baseline file (default: #{DEFAULT_BASELINE_PATH})") do |v|
             options[:baseline] = v
           end
@@ -344,7 +345,7 @@ module Rigor
         }
         parser = OptionParser.new do |opts|
           opts.banner = "Usage: rigor baseline prune [options]"
-          opts.on("--config=PATH", "Path to the Rigor configuration file") { |v| options[:config] = v }
+          Options.add_config(opts, options)
           opts.on("--baseline=PATH", "Path to the baseline file (default: #{DEFAULT_BASELINE_PATH})") do |v|
             options[:baseline] = v
           end

data/lib/rigor/cli/check_command.rb

@@ -6,6 +6,8 @@ require "optionparser"
 
 require_relative "../configuration"
 require_relative "../analysis/result"
+require_relative "../analysis/rule_catalog"
+require_relative "coverage_scan"
 require_relative "command"
 require_relative "options"
 require_relative "diagnostic_formats"
@@ -35,6 +37,7 @@ module Rigor
         return CLI::EXIT_USAGE if buffer == :usage_error
 
         configuration = load_check_configuration(options)
+        configuration = apply_bleeding_edge_override(configuration, options)
         cache_root = configuration.cache_path
         handle_clear_cache(cache_root) if options.fetch(:clear_cache)
 
@@ -48,7 +51,8 @@ module Rigor
         raw_result = runner.run(@argv.empty? ? configuration.paths : @argv)
         result = apply_baseline_filter(raw_result, configuration, options)
 
-        write_result(result, options.fetch(:format))
+        coverage = compute_coverage(runner, configuration, options)
+        write_result(result, options.fetch(:format), coverage: coverage)
         emit_ci_detected_output(result, options)
         write_run_stats(result.stats) if result.stats
         write_trace_appendices
@@ -276,29 +280,18 @@ module Rigor
 
       def parse_check_options # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
         options = {
-          # `nil` triggers `Configuration.discover` (`.rigor.yml` then
-          # `.rigor.dist.yml`); an explicit `--config=PATH` overrides.
           config: nil,
           format: "text",
           explain: false,
           cache_stats: false,
           clear_cache: false,
           no_cache: false,
-          # Run-stats summary (target files, RBS class universe
-          # breakdown, wall time, peak RSS) is on by default
-          # because collection is ~free (single syscall for RSS,
-          # one walk of `class_decl_paths` for the breakdown).
-          # `--no-stats` suppresses it for callers that want a
-          # diagnostic-only output stream.
           stats: true,
           # ADR-15 Phase 4c — when nil, falls back to
           # `RIGOR_RACTOR_WORKERS` then `.rigor.yml`
           # `parallel.workers:` then 0 (sequential). See
           # `resolve_workers` for the precedence chain.
           workers: nil,
-          # Editor mode (`docs/design/20260516-editor-mode.md`).
-          # Both must appear together; the runner uses the pair
-          # to bind an in-flight buffer file to its logical path.
           tmp_file: nil,
           instead_of: nil,
           # ADR-22 — baseline filter. `:unset` means "fall through
@@ -335,17 +328,34 @@ module Rigor
           # the human output; for GitLab / reviewdog-routed CIs, print a
           # one-line hint. On by default; `--no-ci-detect` (or
           # `RIGOR_CI_DETECT=0`) disables it.
-          ci_detect: true
+          ci_detect: true,
+          # ADR-50 § WD2 — the `--bleeding-edge[=ids]` / `--no-bleeding-edge`
+          # CLI mirror of the `bleeding_edge:` config key. `:unset` means "no
+          # flag — use the configured selection"; `true` adopts the whole
+          # overlay, `false` adopts none, and an Array of ids adopts only
+          # those (see `apply_bleeding_edge_override`).
+          bleeding_edge: :unset,
+          # Type-precision coverage block. Off by default — it is a
+          # second precision pass over the analyzed files (the same scan
+          # `rigor coverage` runs), so it is opt-in to keep the default
+          # check path's cost unchanged. When set, `--format json` gains
+          # a `coverage` object (scan_files + precision tiers) and the
+          # text output prints a one-line coverage summary.
+          coverage: false
         }
         parser = OptionParser.new do |opts| # rubocop:disable Metrics/BlockLength
           opts.banner = "Usage: rigor check [options] [paths]"
-          opts.on("--config=PATH", "Path to the Rigor configuration file") { |value| options[:config] = value }
+          Options.add_config(opts, options)
           opts.on("--format=FORMAT",
                   "Output format: text, json, sarif, github, gitlab, checkstyle, junit, teamcity") do |value|
             options[:format] = value
           end
           opts.on("--explain", "Surface fail-soft fallback events as :info diagnostics") { options[:explain] = true }
           opts.on("--cache-stats", "Print on-disk cache inventory at end of run") { options[:cache_stats] = true }
+          opts.on("--coverage",
+                  "Add a type-precision coverage block (an extra precision pass over the analyzed files)") do
+            options[:coverage] = true
+          end
           opts.on("--clear-cache", "Remove the .rigor/cache directory before running") { options[:clear_cache] = true }
           opts.on("--no-cache", "Disable the persistent cache for this run") { options[:no_cache] = true }
           opts.on("--[no-]stats",
@@ -385,6 +395,18 @@ module Rigor
                   "ADR-51: do not auto-emit CI-native output when a CI environment is detected") do
             options[:ci_detect] = false
           end
+          # ADR-50 § WD2 — `=[LIST]` (not ` [LIST]`) so a bare `--bleeding-edge`
+          # never swallows a following positional path: `rigor check
+          # --bleeding-edge lib` adopts the whole overlay and checks `lib`.
+          opts.on("--bleeding-edge=[LIST]",
+                  "ADR-50: adopt the bleeding-edge overlay for this run " \
+                  "(all features, or a comma-separated feature-id list)") do |value|
+            options[:bleeding_edge] = value.nil? || value.split(",").map(&:strip).reject(&:empty?)
+          end
+          opts.on("--no-bleeding-edge",
+                  "ADR-50: ignore any configured bleeding_edge: selection for this run") do
+            options[:bleeding_edge] = false
+          end
         end
         parser.parse!(@argv)
         options
@@ -410,6 +432,20 @@ module Rigor
         Configuration.new(Configuration::DEFAULTS.merge(data))
       end
 
+      # ADR-50 § WD2 — applies the `--bleeding-edge[=ids]` / `--no-bleeding-edge`
+      # CLI selection over the configured `bleeding_edge:` value, mirroring the
+      # CLI-over-config precedence `--workers` and `--no-cache` follow. `:unset`
+      # (no flag) leaves the loaded configuration untouched; any other value is
+      # normalised by {Configuration#with_bleeding_edge}, so the two
+      # `SeverityProfile.resolve` sites (and the worker path, which receives the
+      # whole frozen Configuration) see the run's selection.
+      def apply_bleeding_edge_override(configuration, options)
+        selection = options.fetch(:bleeding_edge)
+        return configuration if selection == :unset
+
+        configuration.with_bleeding_edge(selection)
+      end
+
       def inject_treat_all_as_inline_rbs(entries)
         filtered = entries.reject { |entry| rigor_rbs_inline_entry?(entry) }
         filtered + [{
@@ -635,12 +671,15 @@ module Rigor
         format("%.1f MiB", bytes / (1024.0 * 1024.0))
       end
 
-      def write_result(result, format)
+      def write_result(result, format, coverage: nil)
         case format
         when "json"
-          @out.puts(JSON.pretty_generate(result.to_h))
+          payload = enrich_json(result.to_h)
+          payload["coverage"] = coverage_payload(coverage) if coverage
+          @out.puts(JSON.pretty_generate(payload))
         when "text"
           write_text_result(result)
+          write_coverage_summary(coverage) if coverage
         when ->(fmt) { CLI::DiagnosticFormats.supports?(fmt) }
           # ADR-51 — CI-native renderings (SARIF / GitHub Actions commands /
           # GitLab Code Quality). The `github` form is empty when there are no
@@ -652,6 +691,66 @@ module Rigor
         end
       end
 
+      # Runs the type-precision scan (`--coverage`) over the same file set
+      # the check analyzed and returns a `CoverageReport`, or nil when the
+      # flag is off. It is a second pass — the same scan `rigor coverage`
+      # runs, reused via {CoverageScan} — so it is opt-in to keep the
+      # default check path's cost unchanged.
+      def compute_coverage(runner, configuration, options)
+        return nil unless options.fetch(:coverage)
+
+        files = @argv.empty? ? runner.analysis_file_set : runner.analysis_file_set(@argv)
+        CoverageScan.precision_report(files: files, configuration: configuration)
+      end
+
+      # The `coverage` block embedded in `--format json`. Mirrors the
+      # `summary` of `rigor coverage --format json` (the same vocabulary —
+      # `precise_ratio`, not a separate `typed_ratio`) plus `scan_files`,
+      # so a consumer reads one stream to learn both what fired and how
+      # much of the analyzed surface Rigor could type.
+      def coverage_payload(report)
+        {
+          "scan_files" => report.files.size - report.parse_errors.size,
+          "parse_errors" => report.parse_errors.size,
+          "expressions_typed" => report.grand_total,
+          "precise_count" => report.precise_count,
+          "precise_ratio" => report.precision_ratio.round(4),
+          "dynamic_opaque_count" => report.opaque_count,
+          "dynamic_opaque_ratio" => report.opaque_ratio.round(4)
+        }
+      end
+
+      def write_coverage_summary(report)
+        files = report.files.size - report.parse_errors.size
+        pct = (report.precision_ratio * 100).round(1)
+        @out.puts("Type coverage: #{files} file(s), #{pct}% precise " \
+                  "(#{report.precise_count}/#{report.grand_total} expressions). " \
+                  "Run `rigor coverage` for the full per-file / per-tier breakdown.")
+      end
+
+      # Adds the per-rule `evidence_tier` and `documentation_url` fields
+      # to each diagnostic in the `--format json` payload. Both are pure
+      # functions of the rule id (the rule catalogue, ADR-61 / the
+      # 2026-06-15 feedback §4 + §5.1), so they enrich the presentation
+      # layer here rather than threading through every diagnostic
+      # construction site. Only built-in rules carry catalogue metadata;
+      # plugin / `rbs_extended` / parse-error diagnostics are left
+      # untouched (they host their own documentation and confidence).
+      def enrich_json(payload)
+        Array(payload["diagnostics"]).each do |diag|
+          next unless diag["source_family"] == Analysis::Diagnostic::DEFAULT_SOURCE_FAMILY.to_s
+
+          rule = diag["rule"]
+          next unless rule
+
+          tier = Analysis::RuleCatalog.evidence_tier(rule)
+          diag["evidence_tier"] = tier.to_s if tier
+          url = Analysis::RuleCatalog.documentation_url(rule)
+          diag["documentation_url"] = url if url
+        end
+        payload
+      end
+
       # ADR-51 WD7 — CI auto-detection. Only augments the default human
       # (`text`) output: an explicit `--format` means the caller is in control
       # and is left untouched. For a first-class stdout-native CI (GitHub