rigortype 0.2.0 → 0.2.2

data/data/vendored_gem_sigs/rubygems/rubygems_extras.rbs

@@ -0,0 +1,226 @@
+#
+# Rigor-side supplement to the rbs gem's
+# `core/rubygems/*.rbs` declarations.
+#
+# Re-opens the rubygems classes / Gem module to ADD the
+# declarations the upstream RBS omits. Every block below adds
+# new method signatures only — it does NOT redeclare anything
+# the upstream RBS already covers, so the loader does not raise
+# `RBS::DuplicatedDeclarationError`.
+#
+# Driven by the `references/ruby/lib` survey
+# (`docs/CURRENT_WORK.md` § "Queued engine items") which
+# clusters `undefined-method` on Gem-side selectors most-touched
+# by rubygems' own source tree and by bundler. Returns are
+# `untyped` where Rigor cannot infer a precise shape — the goal
+# is to silence false positives, not to author precise sigs.
+#
+module Gem
+  # Singleton additions surfacing in the survey but absent from
+  # the upstream `core/rubygems/rubygems.rbs`. All are real
+  # methods defined in `lib/rubygems/defaults.rb`,
+  # `lib/rubygems.rb`, or the platform-specific override files.
+  def self.target_rbconfig: () -> untyped
+  def self.set_target_rbconfig: (untyped) -> untyped
+  def self.load_safe_marshal: () -> untyped
+  def self.safe_load_marshal: (untyped) -> untyped
+  def self.verbose: () -> bool
+  def self.really_verbose: () -> bool
+  def self.discover_gems_on_require: () -> bool
+  def self.discover_gems_on_require=: (bool) -> bool
+  def self.default_user_install: () -> bool
+  def self.dynamic_library_suffixes: () -> Array[String]
+  def self.extension_api_version: () -> String
+  def self.find_default_spec: (untyped) -> untyped?
+  def self.install_extension_in_lib: () -> bool
+  def self.load_bundler_extensions: () -> untyped
+  def self.load_plugin_files: (?untyped plugins) -> untyped
+  def self.open_file: (String path, String mode) { (IO) -> untyped } -> untyped
+  def self.open_file_with_lock: (String path) { (IO) -> untyped } -> untyped
+  def self.state_file: () -> String
+  def self.vendor_dir: () -> String
+  def self.activate_bin_path: (String name, ?String exec_name, ?untyped requirements) -> String
+end
+
+class Gem::Platform
+  # `Gem::Platform.new(arg)` is the canonical constructor; the
+  # upstream `core/rubygems/platform.rbs` declares the class
+  # but no `initialize`, which forces RBS to default to
+  # `(): void` and the wrong-arity rule fires for every call
+  # site. The accessor / predicate set covers the most-used
+  # surface bundler and rubygems internals touch.
+  def initialize: (*untyped) -> void
+  attr_accessor cpu: String?
+  attr_accessor os: String?
+  attr_accessor version: String?
+  def to_s: () -> String
+  def ==: (untyped) -> bool
+  def ===: (untyped) -> bool
+  def =~: (untyped) -> bool?
+  def eql?: (untyped) -> bool
+  def hash: () -> Integer
+  def match_spec?: (untyped) -> bool
+  def match_gem?: (untyped, untyped) -> bool
+
+  def self.local: () -> Platform
+  def self.match_spec?: (untyped) -> bool
+  def self.match_gem?: (untyped, untyped) -> bool
+  def self.installable?: (untyped) -> bool
+  def self.sort_priority: (untyped) -> Integer
+end
+
+class Gem::Dependency
+  # `Gem::Dependency.new(name, *requirements, type: :runtime)`.
+  # Upstream RBS declares the class shell but no constructor; a
+  # permissive splat keeps the canonical and the
+  # `(name, requirements, type)` invocation forms both silent.
+  def initialize: (*untyped) -> void
+  attr_accessor name: String
+  attr_accessor requirement: Gem::Requirement
+  attr_accessor type: Symbol
+  attr_accessor prerelease: bool
+  def matches_spec?: (untyped) -> bool
+  def match?: (*untyped) -> bool
+  def to_s: () -> String
+  def ==: (untyped) -> bool
+  def eql?: (untyped) -> bool
+  def hash: () -> Integer
+end
+
+class Gem::Specification
+  def self.find_all_by_name: (String name, *untyped requirements) -> Array[Gem::Specification]
+  def self.stubs: () -> Array[untyped]
+  def self.default_stubs: (?String pattern) -> Array[untyped]
+  def self.reset: () -> void
+  def self.from_yaml: (untyped) -> Gem::Specification
+  def self.load: (String path) -> Gem::Specification?
+  def self._all: () -> Array[Gem::Specification]
+  def self.each: () { (Gem::Specification) -> untyped } -> void
+
+  # Instance-side surface widely used by bundler / rubygems
+  # internals. `attr_accessor` mirrors the writer + reader pair
+  # so the survey's `.name=` / `.version=` / `.full_gem_path=` /
+  # `.loaded_from=` / `.post_install_message=` writes resolve too.
+  def activate: () -> untyped
+  def specification_version: () -> Integer
+  def files: () -> Array[String]
+  def default_gem?: () -> bool
+  def spec_file: () -> String
+  def runtime_dependencies: () -> Array[Gem::Dependency]
+  def required_rubygems_version: () -> Gem::Requirement
+  def required_ruby_version: () -> Gem::Requirement
+  def require_paths: () -> Array[String]
+  attr_accessor name: String
+  attr_accessor version: Gem::Version
+  attr_accessor full_gem_path: String
+  attr_accessor loaded_from: String?
+  attr_accessor post_install_message: String?
+end
+
+class Gem::BasicSpecification
+  def version: () -> Gem::Version
+  def executables: () -> Array[String]
+  def name: () -> String
+  def full_name: () -> String
+  def gem_dir: () -> String
+end
+
+class Gem::Version
+  def segments: () -> Array[untyped]
+end
+
+class Gem::Requirement
+  def requirements: () -> Array[untyped]
+  def self.create: (*untyped) -> Gem::Requirement
+end
+
+class Gem::ConfigFile
+  def []: (untyped) -> untyped
+  def []=: (untyped, untyped) -> untyped
+  def write: () -> void
+  def verbose: () -> bool
+  def verbose=: (bool) -> bool
+  def really_verbose: () -> bool
+  def ssl_ca_cert: () -> String?
+  def ssl_client_cert: () -> String?
+  def ssl_verify_mode: () -> Integer?
+  def credentials_path: () -> String
+  def api_keys: () -> Hash[String, String]
+  def cert_expiration_length_days: () -> Integer
+  def sources: () -> Array[String]
+  def update_sources=: (bool) -> bool
+  def unset_api_key!: () -> bool
+  def state_file_writable?: () -> bool
+  def set_api_key: (untyped host, untyped key) -> untyped
+  def rubygems_api_key: () -> String?
+  def rubygems_api_key=: (String?) -> String?
+  def last_update_check: () -> Integer
+  def last_update_check=: (Integer) -> Integer
+  def ipv4_fallback_enabled: () -> bool
+  def install_extension_in_lib: () -> bool
+  def each: () { ([String, untyped]) -> untyped } -> void
+end
+
+class Gem::LoadError < LoadError
+  attr_accessor name: String
+  attr_accessor requirement: Gem::Requirement
+end
+
+class Gem::SourceList
+  include Enumerable[untyped]
+  def initialize: () -> void
+  def include?: (untyped) -> bool
+  def each: () { (untyped) -> untyped } -> void
+  def to_a: () -> Array[untyped]
+  def from: (untyped) -> SourceList
+end
+
+class Gem::RequestSet
+  def initialize: (*untyped) -> void
+  def import: (untyped) -> untyped
+  def source_set: () -> untyped
+  def installed_gems: () -> Hash[String, untyped]
+  def install: (?untyped options) { (?untyped) -> untyped } -> untyped
+  def install_from_gemdeps: (untyped options) { (?untyped) -> untyped } -> untyped
+  def resolve: (?untyped) -> untyped
+  def resolve_current: () -> untyped
+  def resolve_dependencies: () -> untyped
+  def errors: () -> Array[untyped]
+  attr_accessor remote: bool
+  attr_accessor development: bool
+  attr_accessor development_shallow: bool
+  attr_accessor ignore_dependencies: bool
+  attr_accessor prerelease: bool
+  attr_accessor soft_missing: bool
+  attr_accessor without_groups: Array[Symbol]
+  attr_accessor always_install: untyped
+  attr_accessor installing: bool
+end
+
+class Gem::DependencyInstaller
+  def initialize: (*untyped) -> void
+  def install: (untyped, ?untyped) -> Array[untyped]
+  def installed_gems: () -> Array[untyped]
+  def errors: () -> Array[untyped]
+end
+
+class Gem::Uninstaller
+  def initialize: (*untyped) -> void
+  def uninstall: () -> void
+end
+
+class Gem::PathSupport
+  def initialize: (*untyped) -> void
+end
+
+class Gem::Installer
+  def initialize: (*untyped) -> void
+end
+
+class Gem::DependencyInstaller
+  def initialize: (*untyped) -> void
+end
+
+class Gem::MissingSpecError < StandardError
+  def initialize: (*untyped) -> void
+end

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

@@ -0,0 +1,311 @@
+# Getting started
+
+By the end of this chapter you will be able to:
+
+- get `rigor` onto your `PATH` (the fast AI-assisted way, or
+  by hand);
+- run `rigor check` and read the diagnostics it prints;
+- understand the "no annotations needed" stance that sets
+  Rigor apart from most checkers, and the escape hatches for
+  when inference falls short.
+
+It is the only chapter you must read top to bottom. The rest
+of the handbook is reference you can dip into later.
+
+## Installing Rigor
+
+Rigor is a tool, not a library — like a linter or a compiler, it
+analyses your project but is not part of its runtime. **Do not add
+it to your application's `Gemfile`.** Install it on its own and
+point it at your project.
+
+Rigor itself runs on Ruby 4.0, independently of the Ruby your own
+code targets. The [`target_ruby:` config key](#the-config-file)
+tells Rigor which Ruby *your* project runs.
+
+### The fast path: let an AI agent set it up
+
+If you work with an AI coding agent (Claude Code or any assistant
+that supports [Agent Skills](https://agentskills.io/)), hand it
+this prompt:
+
+```
+Install Rigor in this project by following the instructions at
+https://raw.githubusercontent.com/rigortype/rigor/refs/heads/master/docs/install.md
+```
+
+The agent detects your environment, installs Rigor, then runs the
+**`rigor-project-init` skill** — which walks your `Gemfile`,
+proposes a plugin set matched to your framework, picks an adoption
+mode, and writes `.rigor.dist.yml` for you. No manual YAML editing.
+This is the recommended path; the [config file](#the-config-file)
+section below shows what the skill produces so you can read and
+tweak it afterwards.
+
+The same prompt is available in sixteen languages in the
+[Rails quickstart](../manual/14-rails-quickstart.md#step-1--install-ruby-40-and-rigor-common-to-both-paths).
+
+### The manual path: mise
+
+If you prefer to drive the setup yourself, the recommended runtime
+version manager is [`mise`](https://mise.jdx.dev/), which
+provisions both Ruby 4.0 and Rigor:
+
+```sh
+mise use ruby@4.0
+mise use gem:rigortype
+```
+
+With mise activated in your shell, `rigor` is on your `PATH`. The
+gem is named `rigortype` (the name `rigor` was taken on RubyGems);
+the executable it installs is `rigor`. If you already have Ruby
+4.0, `gem install rigortype` works too.
+
+For shell activation and shims, `asdf`, and developing inside a
+container, see [Installing Rigor](../manual/01-installation.md);
+for continuous integration, see
+[Running Rigor in CI](../manual/11-ci.md).
+
+## What does `rigor check` look at?
+
+Rigor reads your `.rb` files, runs a flow-sensitive type
+inference engine over each one, consults any `sig/*.rbs`
+declarations available to your project, and reports a small
+catalogue of bugs:
+
+- methods called on the wrong receiver class;
+- methods called with the wrong number of arguments;
+- arithmetic that can be proved to raise (`5 / 0`);
+- arguments whose type does not satisfy a refined parameter
+  contract;
+- a few more, all listed in
+  [Chapter 8 — Understanding errors](08-understanding-errors.md).
+
+Rigor does **not** ask you to write type annotations in
+your Ruby source. It infers as much as it can, and stays
+silent everywhere it cannot prove a narrower type.
+A diagnostic only fires when Rigor has enough static
+information to be confident.
+
+## The smallest working session
+
+Drop into your project root and run:
+
+```sh
+rigor check lib
+```
+
+That walks every `.rb` under `lib/`. When the analyzer finds
+nothing to complain about, it prints `No diagnostics` and
+exits `0`:
+
+```text
+No diagnostics
+```
+
+When it does find something, each diagnostic is one line. Given
+this file:
+
+```ruby
+# lib/demo.rb
+"hello".no_such_method        # typo'd method name
+[1, 2, 3].rotate(1, 2)        # too many arguments
+```
+
+`rigor check lib/demo.rb` prints:
+
+```text
+lib/demo.rb:1:9: error: undefined method `no_such_method' for "hello" [call.undefined-method]
+lib/demo.rb:2:11: error: wrong number of arguments to `rotate' on Array (given 2, expected 0..1) [call.wrong-arity]
+```
+
+To run on a single file, pass the file instead of a directory:
+
+```sh
+rigor check path/to/file.rb
+```
+
+And to ask what Rigor inferred at one precise position:
+
+```sh
+rigor type-of lib/foo.rb:10:5
+```
+
+That prints both the rich Rigor type and the conservative
+RBS erasure (the type a non-Rigor RBS tool would see). It is
+the fastest way to ask "what does Rigor think this expression
+produces?"
+
+## Reading a diagnostic
+
+Take the first line from the run above:
+
+```text
+lib/demo.rb:1:9: error: undefined method `no_such_method' for "hello" [call.undefined-method]
+```
+
+| Slice | Meaning |
+| --- | --- |
+| `lib/demo.rb:1:9` | File, 1-indexed line, 1-indexed column |
+| `error` | Severity (`error` / `warning` / `info`) |
+| `undefined method ...` | Human-readable message |
+| `[call.undefined-method]` | The qualified rule identifier |
+
+The qualified rule identifier is the handle you use to silence,
+demote, or look up a rule. The quickest is an in-source comment
+on the offending line:
+
+```ruby
+"hello".no_such_method  # rigor:disable call.undefined-method
+```
+
+The same identifier also drives the `disable:` and
+`severity_overrides:` config keys, and family wildcards work
+(`# rigor:disable call` suppresses every `call.*` rule on that
+line). The full list of families and rules, and when to reach
+for each suppression mechanism, is in
+[Chapter 8 — Understanding errors](08-understanding-errors.md).
+
+## The "no annotations" stance
+
+Most static checkers ask the user to annotate types. Rigor
+does the opposite: it looks at what your Ruby code does and
+**proves** types from the values themselves. Three quick
+examples:
+
+```ruby
+n = 100
+m = n + 1
+assert_type("101", m)     # arithmetic folds
+```
+
+```ruby
+def kind(x)
+  case x
+  when Integer then :int
+  when String  then :str
+  end
+end
+assert_type(":int | :str | nil", kind(7))  # union of all case branches
+```
+
+```ruby
+greeting = "Hello, "                 # Constant<"Hello, ">
+name     = ARGV.first                # String?  (RBS-declared)
+hello    = "#{greeting}#{name}!"     # literal-string carrier:
+                                     # every interpolated part
+                                     # is itself literal-string-
+                                     # compatible, so the result
+                                     # is "provably source-derived"
+```
+
+You did not write a single annotation. Rigor reasons about the
+values directly.
+
+> The `assert_type(...)` line is Rigor's introspection helper,
+> not a runtime check — it pins the inferred type at that point
+> so you can compare the prose to the analyzer's actual output.
+> See [How to read this handbook](README.md#how-to-read-this-handbook)
+> for the full snippet convention.
+
+When inference cannot prove a narrower type, the engine
+returns `Dynamic[top]` (the gradual carrier — "could be any
+Ruby value") and stays silent. Rigor never invents
+diagnostics it cannot prove.
+
+## When inference is not enough
+
+*First read? Skip this section.* Out of the box, inference plus
+any RBS your gems already ship covers most code, and the next
+chapters teach you to read what it produces. Come back here when
+Rigor resolves something to `Dynamic[top]` that you wish it knew
+more about. For most projects only escape hatches (1) and (2)
+ever come up.
+
+There are five escape hatches, in rough order of how often you
+will need them:
+
+1. **Add an `.rbs` file.** Drop a signature into `sig/` and
+   Rigor picks it up automatically. This is the most common
+   reason inference does not see further than the local
+   `def` — by default the analyzer treats every external gem
+   as `Dynamic[top]` unless the gem ships RBS or you
+   opt in to gem-source inference per (4) below.
+2. **Tighten an existing RBS sig with `RBS::Extended`.** Add
+   a `%a{rigor:v1:return: non-empty-string}` annotation
+   above the method's `def ... -> ::String` line. Rigor
+   sees the refinement; ordinary RBS tools see a comment.
+3. **Write a plugin.** When your project has a domain DSL
+   (`Lisp.eval`, `100.kilometers`, `transition_to(:foo)`)
+   that no general-purpose analyzer can know about, a
+   plugin teaches Rigor about it.
+4. **Opt in to gem-source inference.** When a no-RBS gem's
+   methods would otherwise resolve to `Dynamic[top]`, list
+   the gem under `dependencies.source_inference:` in
+   `.rigor.dist.yml` and Rigor will walk its `lib/` the same way
+   it walks project source. Returns are wrapped in
+   `Dynamic[T]` so the call site retains the provenance.
+   See [ADR-10](../adr/10-dependency-source-inference.md)
+   for the trade-offs (per-gem opt-in by design — broad
+   defaults would inflate budgets and make `bundle update`
+   noisy).
+5. **Use the `rigor-sorbet` adapter.** If your project
+   already uses [Sorbet](https://sorbet.org/), Rigor can
+   read your existing `sig { ... }` blocks, RBI files, and
+   `T.let` / `T.cast` / `T.must` / `T.unsafe` assertions
+   as type sources without rewriting anything. See
+   [Chapter 10](10-sorbet.md) for the migration patterns
+   and the translation table.
+
+Chapters 7 and 9 cover (1)–(3) in detail; chapter 10 covers
+(5).
+
+## The config file
+
+The minimum useful run needs no config file at all —
+`rigor check lib` works out of the box. A config file is for
+non-default behaviours: extra `paths`, an alternative
+`severity_profile`, project-wide rule disables, plugins.
+
+If you used the [AI-assisted setup](#the-fast-path-let-an-ai-agent-set-it-up),
+the `rigor-project-init` skill already wrote one for you. To
+write a starter by hand, `rigor init` emits `.rigor.dist.yml`
+— the project default that gets committed:
+
+```yaml
+target_ruby: "3.4"   # your project's Ruby — not Rigor's own 4.0
+
+paths:
+  - lib
+
+# signature_paths: [sig]   # auto-detected when omitted
+
+severity_profile: balanced
+
+# severity_overrides:
+#   call.argument-type-mismatch: warning
+
+# disable: []
+
+# plugins: []
+```
+
+That is all most projects need. The remaining mechanics —
+editor autocomplete from the bundled JSON schema, the
+`.rigor.yml` vs `.rigor.dist.yml` precedence rule, `includes:`
+composition, and how path-bearing keys resolve relative to the
+declaring file — are covered in
+[Configuration](../manual/03-configuration.md). The one rule
+worth knowing up front: when a developer keeps a local
+`.rigor.yml`, it is the *sole* source of config for their runs
+(the two files are never merged automatically), so to extend
+the shared default it must list it under `includes:`.
+
+## What's next
+
+Chapter 2 introduces the carriers Rigor uses to represent
+types — the part of the model that distinguishes Rigor from
+ordinary RBS. After that, Chapter 3 (narrowing) makes the
+carriers come alive: the carriers describe values, and
+narrowing describes how those carriers change as control
+flow passes through `if` / `case` / predicate methods.