rigortype 0.2.0 → 0.2.2

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

@@ -0,0 +1,61 @@
+# rigor-sinatra
+
+Recognises Sinatra's class-level route DSL (`get` / `post` / `put`
+/ `delete` / `head` / `options` / `patch` / `link` / `unlink`) on
+`Sinatra::Base` subclasses and narrows the route block's `self` so
+its bare helpers — `params`, `redirect`, `halt`, `session`,
+`headers`, `content_type`, `erb`, `status`, `body`, … — resolve
+through `Sinatra::Base`'s RBS instead of going unresolved.
+
+It ships bundled in `rigortype`. Activate it under `plugins:`:
+
+```yaml
+plugins:
+  - rigor-sinatra
+```
+
+## What it does
+
+```ruby
+class MyApp < Sinatra::Base
+  get "/users/:id" do
+    halt 404 unless params["id"]
+    redirect "/users/#{params['id']}/profile"
+  end
+end
+```
+
+Inside the route block, `self` is narrowed to `MyApp` (which
+inherits from `Sinatra::Base`), so `params` / `redirect` / `halt`
+resolve through the normal RBS chain. Without the plugin the block
+body is typed as `Singleton[MyApp]` and that per-block resolution is
+lost.
+
+Sinatra's own RBS needs to be available for the helpers to resolve
+— through Rigor's Bundler-awareness, a vendored sig, or (in the
+demo) a local stub.
+
+## No diagnostics, no config
+
+The plugin only recognises the route shape and narrows `self`; it
+emits no diagnostics and has no config keys (the verb match table
+is fixed in the manifest).
+
+## Limitations
+
+- **No routing diagnostics** — path-pattern uniqueness, conflict
+  detection, and named-route reverse lookup are out of scope.
+- **`helpers do … end`** blocks (injecting instance methods) are
+  not handled (that's Tier B / C work, not this Tier A shape).
+- **`configure` / `set` settings DSL** is not handled.
+- **Classic-style top-level routes** — a bare `get '/x' do … end`
+  with no enclosing `class < Sinatra::Base` — are deferred; the
+  recognition needs the receiver's class visible at the call site.
+
+## Plugin internals
+
+The declarative `BlockAsMethod` manifest and the macro-substrate
+`self`-narrowing it rides on are documented in the
+[plugin's README](../../../plugins/rigor-sinatra/README.md). To
+write a plugin, see [`examples/`](../../../examples/README.md) and
+the [`rigor-plugin-author`](../08-skills.md) skill.

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

@@ -0,0 +1,63 @@
+# rigor-sorbet
+
+Lets Rigor read an existing [Sorbet](https://sorbet.org/) codebase
+as a type source: inline `sig { ... }` blocks, RBI files, and the
+`T.let` / `T.cast` / `T.must` / `T.unsafe` / `T.bind` /
+`T.assert_type!` / `T.absurd` assertion forms are translated into
+Rigor's own carriers, so you can run `rigor check` alongside
+`srb tc` without rewriting anything in RBS. It reads source only —
+it does not load `sorbet-runtime`.
+
+It ships bundled in `rigortype`. Activate it under `plugins:`:
+
+```yaml
+plugins:
+  - rigor-sorbet
+```
+
+> **Full guide.** This page is the operational quick reference.
+> The complete walkthrough — the Sorbet→Rigor type-vocabulary
+> table, every assertion form, RBI / Tapioca-DSL handling, sigil
+> semantics, `T.absurd` exhaustiveness, and the migration
+> patterns — is
+> [handbook chapter 10 — Coexisting with Sorbet](../../handbook/10-sorbet.md).
+
+## Configuration
+
+```yaml
+plugins:
+  - gem: rigor-sorbet
+    config:
+      enforce_sigil: true              # default; honour `# typed:` sigils
+      rbi_paths: ["sorbet/rbi"]        # default; set [] to disable RBI loading
+```
+
+- **`enforce_sigil`** (default `true`) — mirror Sorbet's own
+  contract: only record sigs from files at `# typed: true` or
+  stricter. Set `false` to record sigs from every parseable file
+  regardless of sigil. The inline assertion recognisers (`T.let`,
+  `T.cast`, …) always fire, since the user wrote them deliberately.
+- **`rbi_paths`** (default `["sorbet/rbi"]`) — directories of
+  `.rbi` files to load (the standard Tapioca subdirectories
+  `gems/` / `annotations/` / `dsl/` / `shims/` participate by
+  recursion). Set `[]` to opt out, or add a vendored tree.
+
+## Scope and limits
+
+The plugin is **input-side only**: it translates Sorbet's syntax
+into Rigor's type model. It does **not** run Sorbet's checker,
+ship `sorbet-runtime`, or enforce Sorbet's runtime guarantees.
+When an RBS sig and a Sorbet sig disagree, RBS wins (the Sorbet
+sig may refine but not contradict it). Forms outside the
+translation table (`T.proc`, `T.self_type`, `T::Struct` /
+`T::Enum` subclasses, …) degrade to `Dynamic[top]`. Chapter 10
+documents the full vocabulary and these edges.
+
+## Plugin internals
+
+The slice-by-slice implementation (sig parsing, assertion
+lifting, the RBI tree walker, mixin-chain resolution, the
+dispatcher tier ordering), the source layout, and the demo are in
+the [plugin's README](../../../plugins/rigor-sorbet/README.md).
+The design rationale is
+[ADR-11](../../adr/11-sorbet-input-adapter.md).

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

@@ -0,0 +1,75 @@
+# rigor-statesman
+
+Validates `transition_to(:state)` calls against the states declared
+in a `state_machine do … end` block, within the same file. A
+transition to an undeclared state is flagged (with a did-you-mean
+suggestion). It reads source only — no Statesman runtime
+dependency. (The DSL method names are configurable, so it also fits
+AASM-shaped state machines.)
+
+It ships bundled in `rigortype`. Activate it under `plugins:`:
+
+```yaml
+plugins:
+  - rigor-statesman
+```
+
+## What it checks
+
+```ruby
+class Order
+  state_machine do
+    state :draft, initial: true
+    state :submitted
+    state :approved
+  end
+end
+
+order.transition_to(:submitted)   # info:  known state
+order.transition_to(:approval)    # error: unknown state :approval (did you mean :approved?)
+order.transition_to(:purgatory)   # error: unknown state :purgatory
+```
+
+| Rule | Severity | Fires when |
+| --- | --- | --- |
+| `plugin.statesman.known-state` | info | `transition_to(:sym)` where `:sym` is declared in an in-file `state_machine` block |
+| `plugin.statesman.unknown-state` | error | `transition_to(:sym)` where `:sym` is not declared (with a `Base.suggest` did-you-mean) |
+
+Multiple `state_machine` blocks in one file union their states.
+Non-literal-symbol arguments and files with no state machine are
+silently passed through.
+
+## Configuration
+
+```yaml
+plugins:
+  - gem: rigor-statesman
+    config:
+      dsl_method: "state_machine"     # default; the block-opening method
+      state_method: "state"           # default; the state-declaring method
+      transition_method: "transition_to"  # default; the call to validate
+```
+
+Renaming these adapts the plugin to a different state-machine DSL
+(e.g. AASM's `aasm do … state … end`).
+
+## Limitations
+
+- **File-scoped.** States declared in `models/order.rb` aren't
+  visible from another file — each file validates independently.
+- **Literal symbols only.** A variable or method-call argument is
+  not checked.
+- **Receiver-agnostic.** The check fires on any receiver as long as
+  *some* state machine in the file declares the symbol; it does not
+  tie a `transition_to` to a specific machine.
+
+## Plugin internals
+
+`rigor-statesman` is the reference example for the two-pass
+(collect-then-validate) pattern: a `node_file_context` pass
+collects the declared states once, and a `node_rule` validates each
+`transition_to` over the engine-owned walk. The layout, demo, and
+contract surfaces are in the
+[plugin's README](../../../plugins/rigor-statesman/README.md). To
+write a plugin, see [`examples/`](../../../examples/README.md) and
+the [`rigor-plugin-author`](../08-skills.md) skill.

data/docs/manual/plugins/rigor-typescript-utility-types.md

@@ -0,0 +1,71 @@
+# rigor-typescript-utility-types
+
+Maps the TypeScript-canonical utility-type spellings onto Rigor's own
+shape-projection type functions, so a codebase migrating from
+TypeScript / Sorbet RBI can write the familiar names inside
+`RBS::Extended` annotations. It registers five
+[ADR-13](../../adr/13-typenode-resolver-plugin.md) `TypeNodeResolver`s
+as a pure translation layer; the shape *semantics* live in core, where
+they have one spec-owned definition shared by every consumer.
+
+It ships bundled in `rigortype`. Activate it under `plugins:`:
+
+```yaml
+plugins:
+  - rigor-typescript-utility-types
+```
+
+> **Full guide.** The shape projections themselves — what each does,
+> the lossy-projection rule, and the TypeScript→Rigor vocabulary table
+> — are covered in the handbook:
+> [chapter 4 — Tuples and hash shapes](../../handbook/04-tuples-and-shapes.md)
+> § "Deriving new shapes" and the
+> [TypeScript appendix](../../handbook/appendix-typescript.md). This page
+> is the operational quick reference.
+
+## What it resolves
+
+| TypeScript spelling | Rigor core projection |
+| --- | --- |
+| `Pick<T, K>` | `pick_of[T, K]` |
+| `Omit<T, K>` | `omit_of[T, K]` |
+| `Partial<T>` | `partial_of[T]` |
+| `Required<T>` | `required_of[T]` |
+| `Readonly<T>` | `readonly_of[T]` |
+
+```ruby
+class Address
+  # @rbs!
+  #   %a{rigor:v1:return: Pick[Address::Shape, :name | :email]}
+  def public_fields; end
+end
+```
+
+Once the plugin is active, the `Pick[…]` head resolves through the full
+resolution pass (built-ins → plugin chain → RBS Nominal fallback), so
+the sub-arguments may use any of Rigor's existing type vocabulary.
+
+## No configuration
+
+The plugin has no configuration knobs — the resolver chain is
+registered at class load.
+
+## Limitations
+
+- **Unmapped TS names degrade to `Nominal`.** `Parameters<F>`,
+  `ReturnType<F>`, `InstanceType<C>`, `Awaited<P>`, the string-casing
+  utilities (`Uppercase`/`Lowercase`/…), `ThisParameterType`, and
+  `NoInfer` are not mapped — they have no Rigor analogue yet (or need a
+  core operator that hasn't landed) and resolve as `Nominal[Name, […]]`.
+- **Lossy on non-shape carriers.** A projection applied to a bare
+  `Nominal[Hash, [K, V]]` (rather than a `HashShape` / `Tuple`) returns
+  the input unchanged and records a `dynamic.shape.lossy-projection`
+  `:info` diagnostic so you can audit the call site.
+
+## Plugin internals
+
+The five resolver classes, the recursive resolution mechanism, and the
+ADR-13 `TypeNodeResolver` contract are in the
+[plugin's README](../../../plugins/rigor-typescript-utility-types/README.md).
+To write a plugin, see [`examples/`](../../../examples/README.md) and the
+[`rigor-plugin-author`](../08-skills.md) skill.

data/exe/rigor

@@ -8,7 +8,7 @@
 # alias) we re-exec the same command with the flag set before anything
 # else loads. The `RUBY_BOX` guard prevents an infinite re-exec, and the
 # inherited environment (RUBYOPT / BUNDLE_*) preserves the Bundler
-# context across the exec. The `none` (default) and `process` strategies
+# context across the exec. The `none` and `process` (default) strategies
 # need no flag, so this is a no-op for them — behaviour is unchanged
 # unless a project opts into `ruby_box`.
 rigor_isolation = ENV["RIGOR_PLUGIN_ISOLATION"].to_s

data/lib/rigor/analysis/incremental_session.rb

@@ -182,8 +182,10 @@ module Rigor
         @symbol_fingerprints = payload.symbol_fingerprints || {}
         # ADR-46 slice 3 — restore negative edges if present (absent in
         # pre-slice-3 snapshots → empty, which only loses the appeared-symbol
-        # re-check refinement; the fingerprint still drops the snapshot on a
-        # file add/remove, so it is never unsound).
+        # re-check refinement; such a snapshot is never loaded by a slice-3+
+        # engine because the engine version + schema is part of the snapshot
+        # fingerprint, and `--verify-incremental` backstops any residual
+        # under-capture, so it is never unsound).
         @missing           = payload.missing || {}
         @class_decls       = payload.class_decls || {}
         @symbol_dependents = Incremental.invert_symbols(@symbol_sources)

data/lib/rigor/analysis/run_stats.rb

@@ -144,7 +144,19 @@ module Rigor
         out.puts("#{prefix}  Ruby source files: #{@target_files}")
         out.puts("#{prefix}Type universe (symbol discovery; not analyzed for diagnostics)")
         out.puts("#{prefix}  RBS classes available: #{@rbs_classes_total}")
-        if @rbs_attribution_available
+        if @rbs_classes_total.zero?
+          # A normal run always loads the bundled core+stdlib RBS (~1300+
+          # classes), so zero means the environment failed to build (most
+          # often a duplicate declaration in `signature_paths:`) and fell
+          # back to empty — type coverage is then near-useless but the run
+          # still "succeeds". Surface it loudly so a broken setup is not
+          # read as a clean analysis (the 20260620 field trial: redmine
+          # would otherwise wire a 0-coverage check into CI).
+          out.puts("#{prefix}  WARNING: the RBS environment is empty — it failed to build or loaded no")
+          out.puts("#{prefix}           signatures, so type coverage is severely limited (most diagnostics")
+          out.puts("#{prefix}           and coverage cannot fire). Usually a duplicate declaration in")
+          out.puts("#{prefix}           `signature_paths:` — fix it and re-run; the rigor-doctor skill helps.")
+        elsif @rbs_attribution_available
           out.puts("#{prefix}    project sig/:        #{@rbs_classes_project_sig}")
           out.puts("#{prefix}    bundled (core+stdlib+gems): #{@rbs_classes_bundled}")
         elsif @rbs_classes_total.positive?

data/lib/rigor/analysis/runner.rb

@@ -483,19 +483,48 @@ module Rigor
       end
       private :run_project_pre_passes, :adopt_prebuilt_project_scan, :apply_pre_passes_result
 
+      # Ruby versions probed (ascending) to discover the lowest one this
+      # Prism build accepts for `version:`. Prism exposes no version
+      # list, so the floor is found empirically — only when a
+      # misconfigured `target_ruby` is rejected — so the diagnostic can
+      # name it instead of leaving the user to guess (the dogfood field
+      # trial, 20260620-skill-driven-onboarding-dogfood.md, burned cycles
+      # on exactly this).
+      PRISM_VERSION_LADDER = %w[
+        3.0.0 3.1.0 3.2.0 3.3.0 3.4.0 3.5.0 4.0.0 4.1.0 4.2.0
+      ].freeze
+
+      # @return [String, nil] the lowest `target_ruby` this Prism build
+      #   accepts, or nil if none of the ladder parses. Memoised per
+      #   process (the value is constant for a given Prism).
+      def self.prism_supported_floor
+        @prism_supported_floor ||= PRISM_VERSION_LADDER.find do |candidate|
+          Prism.parse("nil", version: candidate)
+          true
+        rescue ArgumentError
+          false
+        end
+      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.
+      # 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 — and name the supported floor + where to read
+      # the right value, so the fix is obvious without a guess-and-retry
+      # loop.
       def validate_target_ruby
         Prism.parse("nil", version: @configuration.target_ruby)
         nil
       rescue ArgumentError => e
+        floor = self.class.prism_supported_floor
         Diagnostic.new(
           path: ".rigor.yml", line: 1, column: 1,
-          message: "target_ruby #{@configuration.target_ruby.inspect} is not accepted by Prism: #{e.message}",
+          message: "target_ruby #{@configuration.target_ruby.inspect} is not supported by this Rigor build " \
+                   "(Prism accepts #{floor} and newer). Set target_ruby to your project's Ruby version " \
+                   "(>= #{floor}) — read it from Gemfile.lock's `RUBY VERSION` or .ruby-version. " \
+                   "(Prism: #{e.message})",
           severity: :error,
           rule: "configuration-error",
           source_family: :builtin
@@ -734,7 +763,7 @@ module Rigor
       # cleanly with no output, which silently masked typos.
       def expand_paths(paths)
         files = []
-        errors = []
+        bad = []
         Array(paths).each do |path|
           if File.directory?(path)
             files.concat(reject_excluded(Dir.glob(File.join(path, RUBY_GLOB))))
@@ -745,12 +774,25 @@ module Rigor
           elsif accept_as_ruby_file?(path)
             files << path
           elsif File.exist?(path)
-            errors << path_error(path, "not a Ruby file (expected `.rb` or a directory)")
+            bad << [path, "not a Ruby file (expected `.rb` or a directory)"]
           else
-            errors << path_error(path, "no such file or directory")
+            bad << [path, "no such file or directory"]
           end
         end
-        { files: files, errors: errors }
+        { files: files, errors: path_expansion_errors(bad, any_files: files.any?) }
+      end
+
+      # A bad path *among valid ones* is a warn-and-skip — the run still
+      # does useful work, so `rigor check app lib` with no `lib/` (the
+      # 20260620 field trial's strap case) analyses `app` instead of
+      # aborting on exit 1. A bad path that leaves NOTHING to analyse
+      # stays an error so a lone typo (`rigor check typo.rb`) is not
+      # silently masked (the regression the path-error check was added
+      # to catch in the first place).
+      def path_expansion_errors(bad, any_files:)
+        severity = any_files ? :warning : :error
+        suffix = any_files ? " (skipped)" : ""
+        bad.map { |path, message| path_error(path, "#{message}#{suffix}", severity: severity) }
       end
 
       def accept_as_ruby_file?(path)
@@ -778,13 +820,13 @@ module Rigor
         @configuration.exclude_patterns.any? { |pattern| File.fnmatch?(pattern, path) }
       end
 
-      def path_error(path, message)
+      def path_error(path, message, severity: :error)
         Diagnostic.new(
           path: path,
           line: 1,
           column: 1,
           message: message,
-          severity: :error
+          severity: severity
         )
       end
 

data/lib/rigor/cli/check_command.rb

@@ -5,6 +5,7 @@ require "json"
 require "optionparser"
 
 require_relative "../configuration"
+require_relative "../config_audit"
 require_relative "../analysis/result"
 require_relative "../analysis/rule_catalog"
 require_relative "coverage_scan"
@@ -38,6 +39,7 @@ module Rigor
 
         configuration = load_check_configuration(options)
         configuration = apply_bleeding_edge_override(configuration, options)
+        config_warnings = warn_unresolved_config(configuration)
         cache_root = configuration.cache_path
         handle_clear_cache(cache_root) if options.fetch(:clear_cache)
 
@@ -52,7 +54,7 @@ module Rigor
         result = apply_baseline_filter(raw_result, configuration, options)
 
         coverage = compute_coverage(runner, configuration, options)
-        write_result(result, options.fetch(:format), coverage: coverage)
+        write_result(result, options.fetch(:format), coverage: coverage, config_warnings: config_warnings)
         emit_ci_detected_output(result, options)
         write_run_stats(result.stats) if result.stats
         write_trace_appendices
@@ -412,6 +414,26 @@ module Rigor
         options
       end
 
+      # Surfaces the class of mistake where a configured value resolves
+      # to nothing — a typo'd or moved `signature_paths:` / bundler /
+      # collection path, an unknown `libraries:` name, an inert
+      # `disable:` / `severity_overrides:` rule id ({ConfigAudit}). The
+      # loader filters each one silently, and the downstream symptom is
+      # confusing: missing signatures turn calls into high-confidence
+      # `call.undefined-method` firings, and an unrecognised suppression
+      # token leaves the rule firing as if the line were never written —
+      # so a one-character mistake can read as hundreds of real errors.
+      # Each finding is emitted to STDERR (a warning, not a hard error —
+      # partial / optional bundles are a valid setup) and the returned
+      # list rides into the `--format=json` payload under `config_warnings`
+      # so CI and framework consumers can assert on it. The audits only
+      # fire on explicit, working-setup-safe signals (see {ConfigAudit}).
+      def warn_unresolved_config(configuration)
+        warnings = ConfigAudit.warnings(configuration)
+        warnings.each { |warning| @err.puts("rigor: #{warning.message}") }
+        warnings
+      end
+
       # ADR-32 WD10 carry-over — wraps `Configuration.load` so the
       # CLI's `--treat-all-as-inline-rbs` flag can inject a
       # `rigor-rbs-inline` plugin entry with
@@ -671,11 +693,12 @@ module Rigor
         format("%.1f MiB", bytes / (1024.0 * 1024.0))
       end
 
-      def write_result(result, format, coverage: nil)
+      def write_result(result, format, coverage: nil, config_warnings: [])
         case format
         when "json"
           payload = enrich_json(result.to_h)
           payload["coverage"] = coverage_payload(coverage) if coverage
+          payload["config_warnings"] = config_warnings.map(&:to_h) unless config_warnings.empty?
           @out.puts(JSON.pretty_generate(payload))
         when "text"
           write_text_result(result)
@@ -776,7 +799,7 @@ module Rigor
       end
 
       def ci_detected_hint(platform)
-        tail = "see `rigor skill print rigor-ci-setup`"
+        tail = "see `rigor skill rigor-ci-setup`"
         if platform.native_artifact?
           "rigor: #{platform.name} detected — for the inline report run " \
             "`rigor check --format #{platform.format}` and publish it as the platform's report artifact (#{tail})."