rigortype 0.2.8 → 0.2.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d38773edf003d6de8ea6ec3de2f19aac4c2d74e404c56f39d1ed9595f388a648
-  data.tar.gz: beb2b7aea30bf74f4cc8d22e66d441d63ecb906689d6a22c6ca647a7a087a719
+  metadata.gz: 565d25fe6c480013419e1e7f6d2bcb60512f7cf56c6a34b612e5951dad8b6c62
+  data.tar.gz: c48e0fcde278beb45ac4b8cb0c5acb272540d8bbc5c37111e983ffacee4c772d
 SHA512:
-  metadata.gz: 1c33b18e310c956f9cc9bbd4806228a095bcf95a137efba50affd49ffca17decac9107006e4a7fd350a9783f289e7d9e336ebc99755e7d69ce321d60b21c731b
-  data.tar.gz: c9f7286bc00f3419083ced2e35678062e8508dfe03b6064fe6c9f4cf4ad752479ca8801cce059cb3fc6bc0ee0eaaa216824a9d43cc93332feb7e267ab988253c
+  metadata.gz: 8859749b0ee71c8dca814c164de8e47bd3004f52773299181f8aeca2bb30b5c96dc47bf46278a3378704f548a30ab68c3cb273b71a2c7346b6bba67bfbfb9365
+  data.tar.gz: 450f2f074e21d3a3fd7cff2e9f7f8971dd838bdfe1fadc0e80300e7c3dc9a98eb13b9890033436b77f5e82196238c91503f598fce78435f9ce9d598c64fd2e87

data/README.md

@@ -231,7 +231,7 @@ rigor docs --list                 # list every bundled page
 
 ## Status
 
-Current release: **`v0.2.8`** (2026-07-06) — the latest cut on the
+Current release: **`v0.2.9`** (2026-07-11) — 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

data/data/core_overlay/csv.rbs

@@ -0,0 +1,28 @@
+# Rigor core overlay — supplemental core signatures.
+#
+# --- CSV::MalformedCSVError.new(message, line_number) ---
+#
+# The pinned `rbs` gem's `csv.rbs` never declares `MalformedCSVError`'s own
+# constructor, so it falls back to the inherited `StandardError#initialize`
+# (arity 0..1). But the `csv` gem's real, documented constructor takes two
+# arguments — the message and the 1-based line number:
+#
+#   raise CSV::MalformedCSVError.new("Unquoted fields...", line)
+#
+# Without the two-arg form a raise like GitLab's
+# `import_csv/base_service.rb` false-fires `call.wrong-arity`
+# ("expected 0..1, got 2"). The line number is optional here so the
+# inherited single-arg form still type-checks.
+
+# `CSV` is a CLASS in Ruby / RBS (a `module CSV` wrapper collides with upstream
+# once the `csv` stdlib is in scope). It must be declared EXPLICITLY here — the
+# overlay loads unconditionally, but `csv` is a stdlib library loaded only on
+# demand, so a bare `class CSV::MalformedCSVError` would make RBS *synthesize*
+# the `CSV` parent namespace (ADR-5) in every env that does not load `csv`,
+# polluting `synthesized_namespaces`. Declaring `class CSV` reopens it cleanly
+# when `csv` is loaded and declares it plainly when it is not.
+class CSV
+  class MalformedCSVError
+    def initialize: (String message, ?Integer line_number) -> void
+  end
+end

data/data/core_overlay/psych.rbs

@@ -0,0 +1,22 @@
+# Rigor core overlay — supplemental core signatures.
+#
+# --- Psych.parse / Psych.parse_stream ---
+#
+# The pinned `rbs` gem's `psych.rbs` declares `Psych.load` / `load_file` /
+# `safe_load` / `unsafe_load*` but omits `Psych.parse` — a real, documented
+# stdlib method (`YAML.parse` is the same method, `YAML` being an alias of
+# `Psych`). It parses one YAML document into a `Psych::Nodes::Document` AST
+# (used for structure-preserving inspection) and raises on a syntax error.
+#
+#   YAML.parse(File.read("config.yml"))   # => Psych::Nodes::Document
+#
+# Without the declaration a call like GitLab's
+# `release_highlights/validator.rb` `YAML.parse(...)` false-fires
+# `call.undefined-method`. The return is left `untyped` — the node AST is
+# rarely consumed with per-method precision, and depending on
+# `Psych::Nodes::Document` being present in the pinned RBS would be brittle.
+
+module Psych
+  def self.parse: (String yaml, ?filename: untyped) -> untyped
+  def self.parse_stream: (String yaml, ?filename: untyped) -> untyped
+end

data/docs/handbook/01-getting-started.md

@@ -87,6 +87,14 @@ silent everywhere it cannot prove a narrower type.
 A diagnostic only fires when Rigor has enough static
 information to be confident.
 
+Where a *signature* does appear in this book — like
+`def foo: (String) -> Integer` — that is **RBS**, Ruby's standard
+signature language; read it as "takes a `String`, returns an
+`Integer`." You write none of it to get started; Rigor consumes
+whatever RBS your gems and the standard library already ship.
+[Chapter 7](07-rbs-and-extended.md) covers RBS in full — if you
+have never seen it, skim that chapter first.
+
 ## The smallest working session
 
 Drop into your project root and run:
@@ -191,7 +199,7 @@ assert_type(":int | :str | nil", kind(7))  # union of all case branches
 
 ```ruby
 greeting = "Hello, "                 # Constant<"Hello, ">
-name     = ARGV.first                # String?  (RBS-declared)
+name     = ARGV.first                # String?  (String or nil — RBS-declared)
 hello    = "#{greeting}#{name}!"     # literal-string carrier:
                                      # every interpolated part
                                      # is itself literal-string-

data/docs/handbook/02-everyday-types.md

@@ -42,7 +42,10 @@ this chapter is the carrier zoo.
 One note on notation before the zoo: angle brackets hold a
 concrete value or bound — `Constant<3>`, `int<0, max>` —
 while square brackets hold type parameters, exactly as in RBS
-— `Nominal[String]`, `Hash[K, V]`, `Dynamic[top]`.
+— `Nominal[String]`, `Hash[K, V]`, `Dynamic[top]`. A type
+parameter names the type of a *part*: `Hash[K, V]` is a Hash
+whose keys are type `K` and values type `V`, just as
+`Array[String]` is "an array of strings."
 
 ## Seeing carriers yourself — `rigor annotate`
 

data/docs/handbook/08-understanding-errors.md

@@ -142,9 +142,9 @@ shipped severities:
 
 | Profile | Behaviour |
 | --- | --- |
-| `lenient` | Most rules → `warning`; uncertain rules drop to `info`. CI-friendly for legacy code. |
-| `balanced` (default) | Most rules → `error`; `dump.type` → `info`. The shipped behaviour. |
-| `strict` | Everything → `error` including the `:warning` rules under `balanced`. Suitable for new projects with no legacy noise. |
+| `lenient` | Only proven rules stay `error` (`call.undefined-method`, `wrong-arity`, `assert.type-mismatch`); uncertain rules drop to `warning`, and several to `off`. For incremental adoption on legacy code. |
+| `balanced` (default) | Most rules → `error`; uncertain rules → `warning`; `dump.type` → `info`. The shipped behaviour. |
+| `strict` | Nearly every rule → `error`. The exceptions: `call.self-undefined-method` stays `off` (opt-in only), and `flow.unreachable-clause` is `warning` (pending its false-positive gate). Suitable for new projects with no legacy noise. |
 
 Set in `.rigor.yml`:
 

data/docs/manual/01-installation.md

@@ -291,6 +291,7 @@ side.
 it for the project, then install the gem into that Ruby:
 
 ```sh
+asdf plugin add ruby        # once, if the ruby plugin isn't added yet
 asdf install ruby latest:4.0
 asdf local ruby latest:4.0
 gem install rigortype

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

@@ -279,6 +279,10 @@ inferring".
 rigor coverage [paths]
 ```
 
+`paths` are files or directories; when omitted, Rigor uses the
+`paths:` list from the configuration file (default `lib`), the same
+as [`rigor check`](#rigor-check).
+
 `--format=text|json` selects the output format and
 `--config=PATH` overrides config discovery. `--threshold=RATIO`
 exits `1` when the precision ratio falls below `RATIO`
@@ -295,7 +299,13 @@ ranked "add a type here" list (the methods most often called on
 an untyped receiver), then the least-protected files;
 `--threshold` and `--format=json` work the same. It is a sound
 upper bound on real protection — a concrete receiver is necessary
-but not sufficient for a diagnostic to fire.
+but not sufficient for a diagnostic to fire. `--workers=N`
+fork-parallelizes the protection scan (both the parameter-inference
+pre-pass and the per-file scan) with output byte-identical to a
+sequential run; it resolves the worker count the same way `check`
+does — `--workers` › `RIGOR_RACTOR_WORKERS` ›
+[`parallel.workers:`](03-configuration.md) › `0` (sequential
+default).
 
 Adding `--mutation` (with `--protection`) switches to the
 **effectiveness** tier: it measures whether Rigor *does* catch a
@@ -403,7 +413,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
-`narrowing_facts`s narrow, and the facts it `produces` /
+`narrowing_facts` hooks 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
@@ -557,8 +567,7 @@ rigor doctor [--config PATH] [--format text|json]
 Runs a scoped analysis and audits:
 
 - **Configuration audit** — unresolved `signature_paths:`, unknown
-  `libraries:`, inert `disable:` / `severity_overrides:` tokens
-  ({ConfigAudit}).
+  `libraries:`, inert `disable:` / `severity_overrides:` tokens.
 - **RBS environment health** — whether the RBS class universe built
   successfully (`0` classes means a broken setup).
 - **Plugin load errors** — whether every configured plugin loaded.
@@ -568,7 +577,7 @@ Runs a scoped analysis and audits:
   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
+routed hint (e.g. "Run `rigor baseline regenerate`"). JSON output
 is a stable contract:
 
 ```json
@@ -585,7 +594,7 @@ 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
+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).
@@ -595,7 +604,7 @@ rigor upgrade
 ```
 
 Until then it prints the current version and notes that upgrade is
-queued.  Exits `0`.
+queued. Exits `0`.
 
 ## Environment variables
 

data/docs/manual/07-plugins.md

@@ -27,7 +27,7 @@ configuration takes the object form:
 plugins:
   - gem: rigor-activerecord
     config:
-      schema: db/schema.rb
+      schema_file: db/schema.rb
 ```
 
 ## Available plugins

data/docs/manual/14-rails-quickstart.md

@@ -27,7 +27,7 @@ You need:
 - **`mise` wired into your shell** — add
   `eval "$(mise activate zsh)"` (or the equivalent for your
   shell) to your shell rc so that `rigor` reaches your `PATH`.
-  See [Installing Rigor § Putting rigor on your PATH](01-installation.md)
+  See [Installing Rigor § Putting rigor on your PATH](01-installation.md#putting-rigor-on-your-path)
   for detail.
 - **An existing Rails project** at a known path.
 
@@ -156,7 +156,9 @@ source-of-truth copy is
 
 If your first `rigor check` reports more than ~100 diagnostics,
 acknowledge mode is the natural starting point. You can tighten
-it later.
+it later. In `.rigor.dist.yml` (Step 3) the mode maps to a
+`severity_profile:` — acknowledge → `lenient`, strict → `strict`
+(omit the key for the default `balanced`).
 
 ### Step 3 — Write .rigor.dist.yml
 

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

@@ -48,6 +48,14 @@ power. `--threshold=RATIO` turns it into a CI gate (exit `1`
 below the ratio) and `--format=json` carries the structured
 fields.
 
+On a large project, `--workers=N` fork-parallelizes the scan
+(both the parameter-inference pre-pass and the per-file scan),
+with output byte-identical to a sequential run. The worker count
+resolves the same way `rigor check` does — `--workers` ›
+`RIGOR_RACTOR_WORKERS` › [`parallel.workers:`](03-configuration.md)
+› `0` (sequential default) — so a project already configured for
+parallel `check` gets parallel coverage for free.
+
 This is the everyday number. When you want the truth behind it,
 move to Tier 2.
 
@@ -200,6 +208,19 @@ 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.
 
+> **`external_gem_without_rbs` needs your gems installed where Rigor
+> can read them.** To tell whether an unresolved constant belongs to
+> a gem, Rigor reads that gem's source — so it must find the gem on
+> disk. It looks in the project's Bundler install tree (a
+> `vendor/bundle`, or a path set with `bundler.bundle_path:`; see
+> [Configuration](03-configuration.md)). A project whose gems live in
+> the active Ruby's default gem home — the common `rbenv` / `mise`
+> case with no `--path` set — is invisible to the isolated analyzer by
+> design ([ADR-27](https://github.com/rigortype/rigor/blob/master/docs/adr/27-tool-distribution-model.md)):
+> point Rigor at it with `bundler.bundle_path:`. Until you do, these
+> holes keep the generic `engine_gap` cause instead of `add_rbs` —
+> the label is missing, never wrong.
+
 Provenance is precision-additive only: it never changes a type, fires
 no diagnostic, and never affects severity or the protection ratio.
 

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

@@ -39,7 +39,7 @@ no-op rather than erroring.
 | `plugin.actionpack.render-target` | info | an explicit `render :symbol` / `"string"` / `partial:` resolved to a view template |
 | `plugin.actionpack.missing-template` | error | an explicit `render` resolved to a view path that doesn't exist under any `view_search_paths` |
 | `plugin.actionpack.permit-call` | info | a `params.require(:m).permit(:key, …)` chain resolved to a known model; keys matched against its columns |
-| `plugin.actionpack.unknown-permit-key` | error | a literal `permit(:key)` isn't a column on the model (with a did-you-mean) |
+| `plugin.actionpack.unknown-permit-key` | error | a literal `permit(:key)` is a near-miss (edit distance ≤ 2) of a real column but not one — a likely typo (with a did-you-mean). A key nothing like any column (a legitimate virtual attribute) does not fire |
 
 Filter and render resolution honours nested-module controller
 qualification (`module Admin; class WidgetsController` resolves

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

@@ -30,9 +30,9 @@ errors_demo.rb:25:1: error: `User.find` expects at least 1 argument, got 0 [plug
 | Recognised `Model.find` / `Model.find_by` / `Model.where` call | `:info` | `plugin.activerecord.model-call` |
 | `Model.find_by(unknown: ...)` / `Model.where(unknown: ...)` | `:error` | `plugin.activerecord.unknown-column` |
 | `Model.find` with 0 args | `:error` | `plugin.activerecord.wrong-arity` |
-| `db/schema.rb` not readable | `:warning` | `plugin.activerecord.load-error` |
+| No schema source (`db/schema.rb` or `db/structure.sql`) readable | `:warning` | `plugin.activerecord.load-error` |
 
-Did-you-mean suggestions use Levenshtein distance ≤ 3 against
+Did-you-mean suggestions use `DidYouMean` fuzzy matching against
 the resolved table's column names.
 
 ## Configuration
@@ -42,13 +42,16 @@ plugins:
   - gem: rigor-activerecord
     config:
       schema_file: "db/schema.rb"                                  # default
+      structure_sql_file: "db/structure.sql"                       # default (fallback when schema_file is absent)
       model_search_paths: ["app/models"]                           # default
       model_base_classes: ["ApplicationRecord", "ActiveRecord::Base"]  # default
 ```
 
-All three keys are optional. Tweak them when:
+All keys are optional. Tweak them when:
 
 - the schema lives elsewhere (`schema_file: "shared/db/schema.rb"`);
+- the project uses `schema_format = :sql` and its dump is not at the
+  default path (`structure_sql_file: "db/structure.sql"`);
 - models are in a non-standard directory
   (`model_search_paths: ["domain/models", "engines/billing/app/models"]`);
 - the base class is custom
@@ -78,8 +81,12 @@ never surfaces a false `call.undefined-method`.
   `User < ApplicationRecord` is not discovered. Either add `User`
   to `model_base_classes`, or list every concrete model
   explicitly.
-- **`db/schema.rb` only.** `db/structure.sql` (raw SQL dumps) is
-  not supported in this iteration.
+- **PostgreSQL `db/structure.sql` fallback.** When `db/schema.rb` is
+  absent, the plugin parses `db/structure.sql` (the `schema_format =
+  :sql` dump) for the same column/type table. It reads PostgreSQL DDL
+  only; a column whose SQL type has no Ruby mapping (a custom enum,
+  `tsvector`, `ltree`) degrades to `Object` (never dropped), and
+  non-`public`-schema partition tables are skipped.
 - **Column reads, not setters.** The plugin types instance-side
   column *reads* (`user.name`, `user.admin?`) and singular
   associations, but not the `name=` setter or the dirty-tracking

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

@@ -59,6 +59,8 @@ plugins:
       routes_file: "config/routes.rb"   # default
       helper_paths: ["app"]             # default; dirs scanned for
                                         # project-defined *_path / *_url methods
+      grape_api_paths: ["lib/api", "app/api"]
+                                        # default; dirs scanned for Grape API classes
 ```
 
 `helper_paths` lets the plugin also register URL builders you
@@ -66,6 +68,15 @@ define yourself (e.g. a private `def callback_url` under
 `app/controllers` or `app/lib`), so calls to them are not flagged
 as unknown helpers.
 
+`grape_api_paths` is where the plugin looks for Grape API classes.
+If you mount one, the `grape-path-helpers` gem generates helpers
+named after each route's path (`api_v4_groups_badges_path`) from
+grape's *runtime* route table, which no static parser can
+enumerate. The plugin reads your API's `prefix` and `version`
+declarations instead and treats the namespace they open as
+unknowable-but-valid, so those calls are never flagged. The `_url`
+form still is: `grape-path-helpers` defines only `_path` helpers.
+
 ## What it provides
 
 The parsed helper table is published as the `:helper_table`