rigortype 0.2.5 → 0.2.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ce4071258582638c452079484534e58c6d6b290a88ea51fdce715024d7c09297
-  data.tar.gz: 90197cb4711899857c8d242470b063e7da64947e46e240253206179a0e8f6baf
+  metadata.gz: c16266bcbae2ff766dd6579df68ca08d31563d7f9a813ef49b88bd8f72734b7a
+  data.tar.gz: c80a5f751c3f757c30acfa0fd1631918a5b3fdc388752c03f27ad56c11a723c2
 SHA512:
-  metadata.gz: 4e967fdc0ca679a712860a20da09842c2668727c0068a4ed9657ae4111d0d94a5ab8efa9684c1a75b1ad25dbeb03efd9a4580f85e771aa5a61a05f56f38b6203
-  data.tar.gz: 8773e6364390cb36296345c4ec8974cee5bec585f7f9da292950859e4cb754081a68130db00dbc14f62d77c7f396477adace7480500d789bb838777ea268c6a2
+  metadata.gz: deda828a4f7171b30c1e0b0531fbb52cb815905e05ebb05186a87b49107d7ce9e80c4d5d9dc81fd35ed26a1872d2d6e9bbeefe98e3b146d1acd1e4d360a81a26
+  data.tar.gz: fbe3ba7eed33351ea7ec8863f09085ed1b55f99e17ac3a0bba51234723da1a35f1e90fa9dd694aa0a680c5dbb8725855deb789728c6886c16ccc229a6d4b1be1

data/README.md

@@ -231,9 +231,10 @@ rigor docs --list                 # list every bundled page
 
 ## Status
 
-Current release: **`v0.2.0`** (2026-06-17) — the first
-publicly-announced (general / evaluation) release. It publishes an
-enumerated [compatibility surface](docs/compatibility.md) as a
+Current release: **`v0.2.7`** (2026-07-05) — the latest cut on the
+`0.2.x` evaluation line opened by `v0.2.0`, the first
+publicly-announced (general / evaluation) release. The line publishes
+an enumerated [compatibility surface](docs/compatibility.md) as a
 minor-non-break trial, rehearsing the contract that hard-freezes at
 `v1.0.0`. Rigor analyses real Ruby today: it has been hardened against
 Mastodon, Redmine, and GitLab FOSS, and the deliberately conservative

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
@@ -452,13 +452,14 @@ The positional slot is a skill *name*; alternative outputs are flags,
 so a skill can never be shadowed by a verb.
 
 ```sh
-rigor skill [<name>] [--path <name>] [--list] [--describe]
+rigor skill [<name>] [--full <name>] [--path <name>] [--list] [--describe]
 ```
 
 | Form | Purpose |
 | --- | --- |
 | (none) / `--list` | Table of every bundled skill (name + absolute path). |
 | `<name>` | Print the `SKILL.md` body to stdout, with a header pointing at the skill's `references/` directory. |
+| `--full <name>` | Print the `SKILL.md` body **followed by every `references/*.md` inline** — the complete, version-current procedure in one call. This is what a skill's "First: load the version-current copy" directive points at, so a copy vendored into a project (e.g. via `npx skills add`) re-fetches its current steps from the installed gem instead of following a frozen copy. |
 | `--path <name>` | Print the single-line absolute `SKILL.md` path, suitable as input to a file-reading tool. |
 | `--describe` | Probe the project's state (config / baseline / `sig/` / CI — presence only, never runs `rigor check`) and recommend the next skill to run. Also spelled `describe`; surfaced top-level as [`rigor describe`](#rigor-describe) below. |
 
@@ -539,6 +540,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/08-skills.md

@@ -108,6 +108,7 @@ source checkout. The `rigor skill` command surfaces them:
 rigor skill describe        # probe the project + recommend the next skill (alias: rigor describe)
 rigor skill --list          # name + absolute path for each bundled skill
 rigor skill <name>          # print the SKILL.md body (with a references/ header)
+rigor skill --full <name>   # the body + every references/*.md inline (complete procedure)
 rigor skill --path <name>   # one-line absolute SKILL.md path, for a file-reading tool
 ```
 
@@ -133,6 +134,26 @@ npx skills add rigortype/rigor
 (The contributor-only skills under `.claude/skills/` are marked internal
 and are not installed by a bulk `npx skills add`.)
 
+### Keeping installed skills current
+
+A skill copied into your project this way is **frozen at install time**,
+while Rigor keeps evolving — flags, config keys, and rule ids move release
+to release. To keep that from going stale (陳腐化), every skill opens with
+a **"First: load the version-current copy"** directive: before following
+its steps, an agent re-fetches the authoritative body from the *installed*
+Rigor with
+
+```sh
+rigor skill --full <name>   # the current body + all its references/, in one call
+```
+
+Because the vendored copy is fixed at install time but `rigor skill` always
+reads the gem, the two diverge as you upgrade, and the directive makes the
+agent prefer the gem's current version. You therefore do **not** need to
+re-install the skills after upgrading Rigor — only the thin entry point
+(`rigor-next-steps`) needs to work before Rigor exists; everything
+version-specific is served live by the installed binary.
+
 ## Running a skill
 
 In an agent that supports Agent Skills, invoke the skill by name (in

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/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

data/lib/rigor/cli/coverage_command.rb

@@ -144,7 +144,7 @@ module Rigor
 
       def scan_protection(paths, options)
         configuration = Configuration.load(options.fetch(:config))
-        environment = project_environment(configuration)
+        environment = plugin_aware_environment(configuration)
         scope = scope_with_inferred_params(paths, configuration, environment)
         scanner = Inference::ProtectionScanner.new(scope: scope)
         accumulator = ProtectionAccumulator.new
@@ -153,21 +153,38 @@ module Rigor
         accumulator.to_report
       end
 
-      # ADR-67 WD3 — seed the call-site parameter-inference table so the
-      # protection scan counts an inferred-parameter receiver (e.g. `node.loc`
-      # where `node` is a `def compile(node)` parameter) as protected when its
-      # call sites resolve to concrete argument types. ONLY the parameter table
-      # is seeded — no cross-file discovery — so every site that does not gain
-      # an inferred parameter type is classified byte-identically to the
-      # un-inferred baseline. Collection spans the scanned `paths`.
+      # Seed the protection scan's scope with the same cross-file facts
+      # `rigor check` resolves against, so a receiver reads the type it
+      # actually has rather than a stripped-scope `Dynamic`:
+      #
+      # - `discovered_classes` — a project constant referring to a class
+      #   defined in a *sibling* file (`Account`, `User`) types as
+      #   `singleton(Account)` instead of `Dynamic`. Without this, a
+      #   single-file scan cannot see a class it does not itself declare,
+      #   so every cross-file class-constant dispatch was miscounted as
+      #   unprotected (the model-constant undercount found 2026-07-04).
+      # - `param_inferred_types` (ADR-67 WD3) — an inferred-parameter
+      #   receiver (`node.loc` where `node` is a `def compile(node)`
+      #   parameter) counts as protected when its call sites resolve to
+      #   concrete argument types.
+      #
+      # Both span the scanned `paths` only (no whole-project pre-pass) —
+      # a site that gains neither is classified exactly as before.
       def scope_with_inferred_params(paths, configuration, environment)
         base = Scope.empty(environment: environment)
+        seed = {}
+
+        discovered = Inference::ScopeIndexer.discovered_classes_for_paths(paths)
+        seed[:discovered_classes] = discovered unless discovered.empty?
+
         table = Inference::ParameterInferenceCollector.collect(
           files: paths, environment: environment, target_ruby: configuration.target_ruby
         )
-        return base if table.empty?
+        seed[:param_inferred_types] = table unless table.empty?
+
+        return base if seed.empty?
 
-        base.with_discovery(base.discovery.with(param_inferred_types: table))
+        base.with_discovery(base.discovery.with(**seed))
       end
 
       def determine_protection_exit(report, options)
@@ -196,6 +213,21 @@ module Rigor
         CoverageScan.project_environment(configuration)
       end
 
+      # The protection scan must see the same receiver types `rigor check`
+      # does — including plugin-contributed `dynamic_return` types (a
+      # controller's `params` → `ActionController::Parameters`, a
+      # `Model.where` → `ActiveRecord::Relation[Model]`). The bare
+      # `project_environment` carries only the RBS environment (no plugin
+      # registry), so every plugin-typed receiver reads `Dynamic` and its
+      # dispatch site is miscounted as *unprotected* — a systematic
+      # undercount of what Rigor actually types on a plugin-using project.
+      # `ProjectContext` builds the plugin-aware environment (registry
+      # materialised + the per-run prepare pass that primes producers like
+      # the controller / model index) exactly as the LSP and the runner do.
+      def plugin_aware_environment(configuration)
+        LanguageServer::ProjectContext.new(configuration: configuration).environment
+      end
+
       def scan_one(path, scanner, accumulator, configuration)
         CoverageScan.scan_into(path, scanner, accumulator, configuration)
       end