rigortype 0.2.4 → 0.2.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 749e0e15c9b85dcec97c9afc1b107d5ebc1a1a685cc19aa39d316a9826992d4a
-  data.tar.gz: 45bcee26284594e35b51a050ce8ac234935bee954063b50fdfe1b0c6a9bcddea
+  metadata.gz: 97d286eb15708fc212260925d407b48926a331798f0d2f210321b1d3c66cda55
+  data.tar.gz: 9fadaf2c31394c142dd15b335dbf740774ceabff8ce85b8a79fcd7faa26ea4fa
 SHA512:
-  metadata.gz: fbf022b6e92a96e1c095cb3d887936161e836201662f051c60de5d0d78494f263228a28df509c3b937768735b5ce18162ee28657b2aaf1cd7a8b2d4851338a53
-  data.tar.gz: a49e89a07950f54fcf8f38e328b8fdb658aaf0802154df457c7b9b1370f35279c1d6d5fe3acf6a45c9e49ff2f7c09ff9f209b1f7dab68d20b283c9baa4b2760b
+  metadata.gz: 1b800eb64d10fdef9039ed429f5740f672cdf0811de86c1cac1434b6bb5a0c820df68d8d8b01aa03ed0cab518d18a6e51af12d608cf6ad50556e4b653a4d3ed6
+  data.tar.gz: 5bee1c072412f7eac14d0c96314f8efe2473cd46efe9763e238bd3c345605deb29055db3601c52909c430d419d8821fc7befb51fe0f5211b8fbb94e379a5d635

data/docs/handbook/09-plugins.md

@@ -68,12 +68,15 @@ directory — gives a plugin five primary surfaces:
    array of `Rigor::Analysis::Diagnostic` rows. The runner
    stamps each with `source_family: "plugin.<your-id>"`.
 2. **`dynamic_return(receivers:, methods:, file_methods:)` /
-   `type_specifier(methods:)`** — the per-call-site return-type
+   `narrowing_facts(methods:)`** — the per-call-site return-type
    and flow-narrowing contribution surface (ADR-37 Slice 2).
    A `dynamic_return` block names the inferred return type at a
    matching call site; the analyzer's dispatcher merges the
    contribution and uses it as if it were RBS-declared. A
-   `type_specifier` block contributes branch-narrowing facts.
+   `narrowing_facts` block contributes branch-narrowing facts.
+   (`narrowing_facts` was renamed from `type_specifier` in ADR-80;
+   `type_specifier` remains as a deprecating alias removed in 0.3.0,
+   so use `narrowing_facts` in new plugins.)
    (These replaced the removed `flow_contribution_for` hook —
    ADR-52 WD3; a plugin that still defines it raises at load.)
 3. **`Plugin::IoBoundary#read_file`** / **`#open_url`** —

data/docs/handbook/appendix-liskov.md

@@ -210,10 +210,12 @@ def shout(thing)
 end
 
 # Clause 1 / covariant returns: the body provably returns the
-# receiver, so #dup returns `self` (Array, not the widened Object).
-# Returning Object would *weaken* the postcondition.
+# receiver, so #dup returns `self` (the receiver's own type, not the
+# widened Object). Returning Object would *weaken* the postcondition.
+# Shape preservation through `dup` (ADR-76 WD2) keeps the precise
+# tuple here rather than degrading to the nominal `Array`.
 copy = [1, 2, 3].dup
-assert_type("Array", copy)
+assert_type("[1, 2, 3]", copy)
 ```
 
 The connection to the type-theory appendix's **gradual guarantee**

data/docs/handbook/appendix-phpstan.md

@@ -96,13 +96,13 @@ When the assertion is recognised by **call shape** rather than
 by signature — PHPStan's `TypeSpecifyingExtension` interface,
 where you write a class that the framework instantiates and
 asks "given this call, what narrowings does it produce?" —
-Rigor's analogue is a plugin's `type_specifier` / `dynamic_return` and
+Rigor's analogue is a plugin's `narrowing_facts` / `dynamic_return` and
 `#diagnostics_for_file` hooks plus the engine's
 `post_return_facts` substrate.
 
 | PHPStan extension type | Rigor analogue |
 | --- | --- |
-| `MethodTypeSpecifyingExtension` | Plugin's `Fact(target_kind: :parameter)` returned from `type_specifier` |
+| `MethodTypeSpecifyingExtension` | Plugin's `Fact(target_kind: :parameter)` returned from `narrowing_facts` |
 | `StaticMethodTypeSpecifyingExtension` | Same, with `Fact(target_kind: :receiver-class)` |
 | `FunctionTypeSpecifyingExtension` | Same, with `Fact(target_kind: :argument)` |
 | `DynamicMethodReturnTypeExtension` | Plugin's `dynamic_return(methods:) { |call_node, scope, ...| ... }` |

data/docs/install.md

@@ -152,7 +152,7 @@ without WSL). For all other environments, prefer Case A–D above.
 rigor --version
 ```
 
-A version string like `rigor 0.1.x` confirms a successful install.
+A version string like `rigor 0.2.x` confirms a successful install.
 If the command is not found, revisit Step 2 for your case.
 
 ---

data/docs/manual/02-cli-reference.md

@@ -403,7 +403,7 @@ catalogue** ([ADR-37](../adr/37-plugin-interface-segregation.md)):
 a focused, machine-readable map of what each loaded plugin
 contributes — the AST node types its `node_rule`s match, the
 receiver classes its `dynamic_return`s gate on, the methods its
-`type_specifier`s narrow, and the facts it `produces` /
+`narrowing_facts`s narrow, and the facts it `produces` /
 `consumes`. Combine with `--format=json` for tooling (an AI
 agent can enumerate every plugin's behaviour without reading a
 line of plugin source). The same narrow surfaces also appear in
@@ -539,6 +539,63 @@ with its stable id, the severity it would impose, and whether your config
 adopts it. See [`docs/compatibility.md`](../compatibility.md) for how
 bleeding-edge fits the stability model.
 
+## `rigor doctor`
+
+Classify setup problems vs a clean run with routed next actions
+([ADR-77](../adr/77-doctor-and-upgrade-commands.md) WD1).
+
+```sh
+rigor doctor [--config PATH] [--format text|json]
+```
+
+| Flag | Purpose |
+| --- | --- |
+| `--config PATH` | Use this `.rigor.yml` instead of auto-discovery. |
+| `--format text\|json` | Output format. Default `text`. |
+
+Runs a scoped analysis and audits:
+
+- **Configuration audit** — unresolved `signature_paths:`, unknown
+  `libraries:`, inert `disable:` / `severity_overrides:` tokens
+  ({ConfigAudit}).
+- **RBS environment health** — whether the RBS class universe built
+  successfully (`0` classes means a broken setup).
+- **Plugin load errors** — whether every configured plugin loaded.
+- **Baseline drift** — whether the current diagnostics have drifted
+  from the saved baseline.
+- **Rails plugin gap** — whether `Gemfile.lock` contains Rails gems
+  but no Rails plugin is enabled.
+
+Text output prints `[PASS]`, `[FAIL]`, or `[WARN]` per check plus a
+routed hint (e.g. "Run `rigor baseline regenerate`").  JSON output
+is a stable contract:
+
+```json
+{
+  "status": "issues_found",
+  "checks": [
+    { "id": "config_audit", "status": "fail", "message": "...", "hint": "..." }
+  ]
+}
+```
+
+Exits `1` when any check fails, `0` when all pass.
+
+## `rigor upgrade`
+
+Migration command skeleton ([ADR-50](../adr/50-release-engineering-and-stability-strategy.md)
+WD7).  The real body lands when a concrete backwards-compatibility
+break gives it a target (e.g. re-running `baseline regenerate`
+against a strengthened default profile, surfacing renamed
+suppression ids, reporting `bleeding_edge:` graduations).
+
+```sh
+rigor upgrade
+```
+
+Until then it prints the current version and notes that upgrade is
+queued.  Exits `0`.
+
 ## Environment variables
 
 Most behaviour is driven by flags and `.rigor.yml`; a few

data/docs/manual/06-baseline.md

@@ -77,6 +77,18 @@ a diagnostic another layer has already suppressed.
 default — one bucket per file × rule) or `--match-mode=message`
 (a bucket per distinct message: more precise, more churn).
 
+`--match-mode=message` keys each bucket on the **rendered
+message text**, which includes details such as the displayed
+receiver type. That makes it sharper at telling two same-rule
+diagnostics on one line apart, but also **brittle**: when a Rigor
+upgrade rewords a message or changes how a type is displayed, the
+key no longer matches and the previously-baselined diagnostic
+resurfaces as if new. `--match-mode=rule` keys only on
+`(file, rule)` and is immune to message rewording — prefer it
+unless you specifically need per-message discrimination, and
+expect to `regenerate` a `message`-mode baseline after upgrading
+Rigor.
+
 ## Working a baseline down
 
 `rigor triage` summarises a diagnostic stream — rule

data/docs/manual/11-ci.md

@@ -192,9 +192,9 @@ remains available for any other tool that wants the raw diagnostic stream.
 
 The workflow above installs whatever `rigortype` is current at run
 time. To pin a version — and keep CI reproducible — choose one of the
-options below. While the `0.1.x` line is in preview the surface is
-still settling, so pinning is recommended; what Rigor commits to
-keeping stable (and from which release) is enumerated in
+options below. While the `0.2.x` line is an evaluation trial the
+surface is still settling, so pinning is recommended; what Rigor
+commits to keeping stable (and from which release) is enumerated in
 [`docs/compatibility.md`](../compatibility.md).
 
 ### A CI-only `Gemfile` (recommended)
@@ -203,7 +203,7 @@ Commit a two-line `.github/rigor/Gemfile`:
 
 ```ruby
 source "https://rubygems.org"
-gem "rigortype", "~> 0.1"
+gem "rigortype", "~> 0.2"
 ```
 
 plus its `Gemfile.lock`, and point the Rigor job at it through
@@ -242,7 +242,7 @@ updates:
 
 ### A pinned `gem install`
 
-`gem install rigortype -v "0.1.15"` in the workflow. Simpler, with no
+`gem install rigortype -v "0.2.6"` in the workflow. Simpler, with no
 extra files — but Dependabot does not see a version inside a `run:`
 step, so updates to the pin are manual.
 
@@ -258,7 +258,7 @@ docker run --rm -v "$PWD:/src" ghcr.io/rigortype/rigor check
 
 `rigor` is the image entrypoint, so subcommands and flags follow the
 image name. Pin a version with an explicit tag —
-`ghcr.io/rigortype/rigor:0.1.15`.
+`ghcr.io/rigortype/rigor:0.2.6`.
 
 ## Nix
 

data/docs/manual/15-type-protection-coverage.md

@@ -172,6 +172,35 @@ breakage a *different* test would catch shows as a gap). For an
 accurate map, run the command over all tests that exercise the
 files you are measuring — trading time for completeness.
 
+### Why a hole is untyped — provenance and tractability
+
+For a `Dynamic`-receiver hole, `rigor coverage --protection` also
+records *why* the receiver is untyped and *whether a type can close
+it*, so you spend effort where it pays off. Each `add_a_type_here`
+entry carries two fields:
+
+- **`dynamic_origin`** — the cause the value became dynamic:
+  `external_gem_without_rbs`, `framework_dsl_boundary`,
+  `analyzer_budget_cutoff`, `explicit_untyped`, or
+  `unsupported_syntax`.
+- **`tractability`** — the action axis derived from that cause:
+  - **`add_rbs`** — you can close it with a type: install RBS
+    (`rbs collection install`), enable `dependencies.source_inference:`,
+    or tighten an authored `untyped` signature.
+  - **`enable_plugin`** — a framework / DSL boundary; reach for a
+    plugin or [`pre_eval:`](03-configuration.md), not a hand-written
+    type.
+  - **`engine_gap`** — not closable by a user type (a budget cutoff
+    or a construct Rigor does not yet model); report it.
+
+The text report prints a one-line `by tractability:` breakdown under
+the "Add a type here" header, and the JSON carries the same totals as
+`tractability_summary`. Start with the `add_rbs` holes — they are the
+ones a type actually catches.
+
+Provenance is precision-additive only: it never changes a type, fires
+no diagnostic, and never affects severity or the protection ratio.
+
 ## Cost and scope
 
 The fused tiers run real analyses and real test suites, so treat

data/docs/manual/plugins/rigor-minitest.md

@@ -79,7 +79,7 @@ matches.
 ## Plugin internals
 
 The assertion recogniser and the contract surfaces this plugin
-exercises — the ADR-37 `type_specifier` narrowing gate and the ADR-38
+exercises — the ADR-37 `narrowing_facts` narrowing gate and the ADR-38
 `additional_initializers` for `setup` — are in the
 [plugin's README](../../../plugins/rigor-minitest/README.md). To write a
 plugin, see [`examples/`](../../../examples/README.md) and the

data/docs/manual/plugins/rigor-rails-i18n.md

@@ -43,9 +43,14 @@ errors_demo.rb:25:1: warning: `t('errors.messages.blank')` is missing from local
 with a literal first argument. **Lazy keys** — `t('.title')` in a
 controller — are expanded to `<controller_scope>.<action>.<key>`
 from the file path and the innermost enclosing `def`, matching
-Rails' convention; lazy keys in non-controller files are skipped
-(the scope can't be determined statically). Calls with a
-non-literal key (`t(some_variable)`) pass through unchecked.
+Rails' convention; lazy keys in non-controller Ruby files (models,
+helpers, mailers) are skipped (the scope can't be determined
+statically at that point). **View template lazy keys** —
+`t('.title')` inside `app/views/setting/index.html.erb` expands
+to `setting.index.title` and is validated for key existence and
+per-locale coverage; ERB, Haml, and Slim templates under
+`view_search_paths` (default `app/views`) are scanned. Calls with
+a non-literal key (`t(some_variable)`) pass through unchecked.
 
 Keys under the prefixes Rails and the `rails-i18n` gem ship
 themselves (`date.` / `time.` / `datetime.` / `number.` /
@@ -62,11 +67,14 @@ plugins:
     config:
       locale_search_paths: ["config/locales"]   # default
       configured_locales: ["en"]                # default
+      view_search_paths: ["app/views"]          # default
 ```
 
 `configured_locales` is the set of locales the project ships;
 setting it to `["en", "ja"]` turns on `missing-locale` warnings
 whenever a key resolves in one but not the other.
+`view_search_paths` controls which directories are scanned for
+view templates containing lazy `t('.key')` calls.
 
 ## Limitations
 
@@ -74,6 +82,17 @@ whenever a key resolves in one but not the other.
 - **Lazy keys outside controllers are skipped** — the
   controller/action scope `t('.x')` depends on isn't derivable in
   a model / helper / mailer.
+- **View template lazy keys** (`t('.key')` inside ERB / Haml /
+  Slim) are validated for key existence and per-locale coverage.
+  Interpolation validation is skipped for templates — the hash
+  may come from controller instance variables not visible in the
+  template source. Configure `view_search_paths:` to override the
+  default `["app/views"]`.
+- **View diagnostics duplicate under `--workers`** — the view
+  scan is a project-wide pass surfaced through the per-file
+  diagnostic hook, so each fork-pool worker re-emits the full set
+  (the same once-per-run limitation the `load-error` diagnostics
+  carry). Default `rigor check` (sequential) is unaffected.
 - **Pluralization is recognised but not validated** — `count:` is
   treated as a reserved option; whether the locale defines
   `:zero` / `:one` / `:other` is not checked.

data/lib/rigor/analysis/incremental_session.rb

@@ -35,9 +35,14 @@ module Rigor
 
       # @param paths [Array<String>, nil] explicit analysis roots; nil
       #   (the default) uses the configuration's `paths:`.
-      def initialize(configuration:, paths: nil)
+      # @param environment [Rigor::Environment, nil] optional shared
+      #   environment to thread into each internal Runner. Long-lived
+      #   callers and specs can use this to avoid rebuilding the same
+      #   RBS universe for every baseline / recheck / oracle run.
+      def initialize(configuration:, paths: nil, environment: nil)
         @configuration = configuration
         @paths = paths
+        @environment = environment
         @cache = {}              # analyzed path => [Diagnostic]
         @sources = {}            # analyzed path => Set<source path it read from>
         @digests = {}            # analyzed path => content digest at last analysis
@@ -312,7 +317,7 @@ module Rigor
       end
 
       def build_runner(**)
-        Runner.new(configuration: @configuration, cache_store: nil, **)
+        Runner.new(configuration: @configuration, cache_store: nil, environment: @environment, **)
       end
 
       # Run the runner over the session's explicit paths (or, when none were

data/lib/rigor/cli/check_command.rb

@@ -13,6 +13,7 @@ require_relative "command"
 require_relative "options"
 require_relative "diagnostic_formats"
 require_relative "ci_detector"
+require_relative "check_runner_factory"
 
 module Rigor
   class CLI
@@ -244,42 +245,12 @@ module Rigor
       end
 
       def build_check_runner(configuration:, options:, buffer:, cache_root:)
-        cache_store = if options.fetch(:no_cache)
-                        nil
-                      else
-                        Cache::Store.new(
-                          root: cache_root,
-                          max_bytes: configuration.cache_max_bytes
-                        )
-                      end
-        Analysis::Runner.new(
-          configuration: configuration,
-          explain: options.fetch(:explain),
-          cache_store: cache_store,
-          collect_stats: options.fetch(:stats),
-          workers: resolve_workers(options, configuration),
-          buffer: buffer
+        CheckRunnerFactory.build(
+          configuration: configuration, options: options,
+          buffer: buffer, cache_root: cache_root
         )
       end
 
-      # ADR-15 Phase 4c — resolves the worker count by
-      # precedence: CLI `--workers=N` (most explicit) > env
-      # `RIGOR_RACTOR_WORKERS` > config `.rigor.yml`
-      # `parallel.workers:` > 0 (sequential default). Returns
-      # an Integer; non-numeric values raise so typos fail
-      # loudly. CLI / env may pass a negative value — clamped
-      # to 0 (sequential) so a stray `-1` doesn't crash the
-      # pool spawn loop.
-      def resolve_workers(options, configuration)
-        cli_value = options[:workers]
-        return [Integer(cli_value), 0].max if cli_value
-
-        env_value = ENV.fetch("RIGOR_RACTOR_WORKERS", nil)
-        return [Integer(env_value), 0].max if env_value && !env_value.empty?
-
-        configuration.parallel_workers
-      end
-
       def parse_check_options # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
         options = {
           config: nil,

data/lib/rigor/cli/check_runner_factory.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require_relative "../analysis/runner"
+require_relative "../cache/store"
+
+module Rigor
+  class CLI
+    # Shared factory for building an {Analysis::Runner} from CLI option
+    # hashes + a loaded {Configuration}.
+    #
+    # Extracted from {CheckCommand} so that `rigor doctor` and future
+    # `describe --deep` can reuse the exact same runner-setup logic
+    # (cache, workers, buffer, explain) without diverging from the
+    # primary check path (ADR-77 WD3).
+    module CheckRunnerFactory
+      module_function
+
+      # Builds a runner matching the configuration/plugin/cache resolution
+      # that `rigor check` itself uses.
+      #
+      # @param configuration [Rigor::Configuration]
+      # @param options [Hash] parsed CLI options (must contain at least
+      #   `:no_cache`, `:explain`, `:stats`, `:workers`)
+      # @param buffer [Rigor::Analysis::BufferBinding, nil]
+      # @param cache_root [String]
+      # @return [Rigor::Analysis::Runner]
+      def build(configuration:, options:, buffer:, cache_root:)
+        cache_store = if options.fetch(:no_cache)
+                        nil
+                      else
+                        Cache::Store.new(
+                          root: cache_root,
+                          max_bytes: configuration.cache_max_bytes
+                        )
+                      end
+        Analysis::Runner.new(
+          configuration: configuration,
+          explain: options.fetch(:explain),
+          cache_store: cache_store,
+          collect_stats: options.fetch(:stats),
+          workers: resolve_workers(options, configuration),
+          buffer: buffer
+        )
+      end
+
+      # Resolves the worker count by precedence: CLI `--workers=N`
+      # (most explicit) > env `RIGOR_RACTOR_WORKERS` > config
+      # `.rigor.yml` `parallel.workers:` > 0 (sequential default).
+      # Returns an Integer; non-numeric values raise so typos fail
+      # loudly. CLI / env may pass a negative value — clamped to 0
+      # (sequential) so a stray `-1` doesn't crash the pool spawn loop.
+      def resolve_workers(options, configuration)
+        cli_value = options[:workers]
+        return [Integer(cli_value), 0].max if cli_value
+
+        env_value = ENV.fetch("RIGOR_RACTOR_WORKERS", nil)
+        return [Integer(env_value), 0].max if env_value && !env_value.empty?
+
+        configuration.parallel_workers
+      end
+    end
+  end
+end