rigortype 0.0.4 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 23970981c0d0b952bc6885102dcf163fbb0cd0f00e4bb2232300676a6904d3a3
-  data.tar.gz: 07211b55ad358bcb535de36b86d00465c5ba708197ce0945667386b2eca0e3eb
+  metadata.gz: 3b0e7446849097317ae0f4a26114036f41c4ad321abfcc492d25ac67995150b6
+  data.tar.gz: 95736bd636be7ba8698d4bf9a4cbdcbf870eaaf5a9117207f238f7429e064e94
 SHA512:
-  metadata.gz: 170f4ce6750090993b14cc4d899d2cf89a89cf1c2a0a086188988a9062b70d569db78488efa4d25805a42204f4b62ad02fee2f812ad51d36008bb75d648b58bf
-  data.tar.gz: 63df03ee2ef43fa69716911399d971e48da46567ab4f6b5dd4b9ee5c3543fca2db5a169f12f84c4a3964a293f50704190439fc1d32475f41808bfdac771eb50a
+  metadata.gz: b16976fea05e9c4f9d9f9247e5858817e9938eff6329ce7e091f7c9196051170f3a36c528e6f6cb0386f4762c8b17302a6bb3a9df239e9385ec375a2c1b3a6ca
+  data.tar.gz: c8ac86259a502f4bfac5ef51464cf5eea45d599bdd3f9d164798b5b66a8257a8a117ea4e54b2314c27da9845a3723fa3fca61fe2f259988f2e19eb9b79c9df6d

data/README.md

@@ -1,169 +1,250 @@
 # Rigor
 
-Rigor is a static analyzer for Ruby that aims to provide modern,
-inference-first type checking without adding type annotations or
-runtime dependencies to application code.
-
-This first preview ships a usable end-to-end pipeline: parse Ruby
-with Prism, build a flow-sensitive type-inference engine
-(`Rigor::Scope#type_of`), drive a project-aware RBS environment,
-and surface diagnostics through a small `rigor check` rule
-catalogue.
-
-## Status
+[![Gem Version](https://badge.fury.io/rb/rigortype.svg?icon=si%3Arubygems)](https://badge.fury.io/rb/rigortype)
+![GitHub License](https://img.shields.io/github/license/rigortype/rigor)
+
+**Inference-first static analysis for Ruby.** Add Rigor to your
+Gemfile and run `rigor check` over your code — no annotations,
+no runtime dependency on the analyzer, no DSL.
+
+Rigor parses Ruby with [Prism](https://github.com/ruby/prism),
+runs a flow-sensitive type-inference engine over each file,
+consults RBS signatures and the project's own `sig/` directory
+for any class it can find, and reports a small but trustworthy
+catalogue of bugs (undefined methods on typed receivers, wrong
+positional arity, provable `Integer / 0`, …).
+
+When you want tighter types than RBS expresses, refine them
+through the
+[`RBS::Extended`](docs/type-specification/rbs-extended.md)
+annotation surface — `rigor:v1:return:` /
+`rigor:v1:param:` / `rigor:v1:assert` directives accept the
+imported-built-in refinement names (`non-empty-string`,
+`positive-int`, `non-empty-array[Integer]`, `int<5, 10>`, …)
+without changing the underlying RBS.
+
+## Installation
+
+Add the gem to your application's Gemfile (development group is
+typical — Rigor is a static analyzer, not a runtime dependency):
+
+```ruby
+group :development do
+  gem "rigortype", require: false
+end
+```
 
-`master` is at the **fourth preview** (`v0.0.4`). The engine
-recognises the bulk of canonical Ruby surface — local variables,
-ivars / cvars / globals (intra- and cross-method), self typing,
-lexical constant lookup, predicate narrowing
-(`is_a?` / `==` / `===` / `case`-`when`), block parameter binding,
-closure escape, Tuple / HashShape carriers — plus the v0.0.3
-constant-folding surface and the v0.0.4 refinement-carrier
-catalogue (`Type::Difference` / `Type::Refined` / `Type::Intersection`,
-14 imported built-in refinement names through
-`Builtins::ImportedRefinements`, and the symmetric
-`rigor:v1:return:` / `rigor:v1:param:` / `rigor:v1:assert:`
-RBS::Extended directive routes). See [CHANGELOG.md](CHANGELOG.md)
-for the per-release surface and
-[docs/CURRENT_WORK.md](docs/CURRENT_WORK.md) for the live slice
-trail.
-
-## Requirements
-
-- Nix with the `nix-command` and `flakes` features available.
-- Ruby 4.0.x and Bundler 4.x, provided by the Flake development
-  shell.
-
-## Setup
+Install:
 
 ```sh
-nix --extra-experimental-features 'nix-command flakes' develop --command bundle install
-nix --extra-experimental-features 'nix-command flakes' develop --command bundle exec rake
+bundle install
 ```
 
-For interactive development, enter the Flake shell first:
+Or, for a one-off install outside Bundler:
 
 ```sh
-nix --extra-experimental-features 'nix-command flakes' develop
+gem install rigortype
 ```
 
-## Quick Start
+The gem ships an executable named `rigor` (gem name is
+`rigortype` because `rigor` was already taken on RubyGems).
 
-Inside the Flake shell:
+**Ruby version.** The gemspec requires `>= 4.0.0, < 4.1`.
 
-```sh
-# Show available subcommands.
-bundle exec exe/rigor help
+## First analysis
+
+Drop into your project root and run the canonical commands:
 
-# Print the inferred type at FILE:LINE:COL.
-bundle exec exe/rigor type-of lib/rigor/scope.rb:55:9
+```sh
+# Diagnose unknown methods, wrong-arity calls, and other
+# rule-driven bugs across `lib/`.
+bundle exec rigor check lib
 
-# Report Scope#type_of coverage across a tree.
-bundle exec exe/rigor type-scan lib
+# Print the inferred type at a precise FILE:LINE:COL position.
+bundle exec rigor type-of lib/foo.rb:10:5
 
-# Diagnose unknown methods and wrong-arity calls on typed receivers.
-bundle exec exe/rigor check lib
+# Report Scope#type_of coverage across a tree (handy when
+# diagnosing why a particular call site reads as `untyped`).
+bundle exec rigor type-scan lib
 
-# Write a starter .rigor.yml.
-bundle exec exe/rigor init
+# Drop a starter .rigor.yml into the project root.
+bundle exec rigor init
 ```
 
-### Example diagnostics
-
-`rigor check` reports the canonical type-check signals it can
-prove against the loaded RBS environment:
+### Sample output
 
 ```sh
 $ cat /tmp/demo.rb
-"hello".no_such_method        # bug: undefined method
-[1, 2, 3].rotate(1, 2)        # bug: wrong number of arguments
+"hello".no_such_method        # undefined method
+[1, 2, 3].rotate(1, 2)        # wrong number of arguments
 
-$ bundle exec exe/rigor check /tmp/demo.rb
+$ bundle exec rigor check /tmp/demo.rb
 /tmp/demo.rb:1:9: error: undefined method `no_such_method' for "hello"
 /tmp/demo.rb:2:11: error: wrong number of arguments to `rotate' on Array (given 2, expected 0..1)
 ```
 
-The rule catalogue is intentionally narrow: a diagnostic fires
-only when the receiver type is statically known and the method
-set on that class is enumerable through RBS or in-source `def` /
-`define_method` discovery. Implicit-self calls, dynamic
-receivers, and constant-decl alias classes (e.g. `YAML` → `Psych`)
-are skipped to avoid false positives.
-
-## What works
-
-The first preview engine resolves:
-
-- **Local / instance / class / global variables** — intra-method
-  bindings (`@x = 1; @x`), cross-method ivar / cvar accumulators
-  (`def init; @x = 1; end; def get; @x; end`), program-wide
-  globals.
-- **Compound writes** — `||=`, `&&=`, `+=` and friends thread
-  through scope for every variable kind.
-- **`self` typing** — class- and method-body boundaries inject
-  `Singleton[T]` / `Nominal[T]`; implicit-self call dispatch
-  routes through the enclosing class's RBS.
-- **Constant lookup** — lexical walk against `scope.self_type`,
-  RBS-core, common stdlib (`pathname`, `optparse`, `json`,
-  `yaml`, ...), the `prism` and `rbs` gems' RBS, in-source
-  class discovery, and in-source constant value tracking
-  (`BUCKETS = [:a, :b, :c]; BUCKETS.first` → `Constant[:a]`).
+The rule catalogue is **deliberately conservative**: a
+diagnostic fires only when the receiver type is statically
+known and the method set on that class is enumerable through
+RBS or in-source `def` / `define_method` discovery. Implicit-
+self calls, dynamic receivers, and constant-decl alias classes
+(e.g. `YAML` → `Psych`) are skipped to avoid false positives.
+
+## How Rigor finds your types
+
+Rigor consults, in order:
+
+1. **In-source RBS.** If your project has a `sig/` directory,
+   Rigor auto-loads it. `rigor init` writes a `.rigor.yml`
+   that points at `sig/` by default.
+2. **Bundled RBS core + stdlib.** Pathname, OptParse, JSON,
+   YAML, etc. ship with the analyzer.
+3. **Gem RBS.** RBS files vendored with installed gems
+   (Prism's own `.rbs`, the `rbs` gem's, …).
+4. **In-source class discovery.** When no RBS is available,
+   Rigor walks `def` / `define_method` / `attr_*` so
+   user-defined methods on a class are recognised.
+
+If a type cannot be proved, the engine returns `Dynamic[Top]`
+(Rigor's gradual carrier) and stays silent — Rigor never invents
+diagnostics it cannot prove.
+
+## Refining types through `RBS::Extended`
+
+When the RBS-declared type is too wide, attach a
+`%a{rigor:v1:…}` annotation to the relevant method in your
+`sig/` file. The annotation is a no-op for ordinary RBS tools
+and a tightening signal for Rigor.
+
+```rbs
+class Slug
+  # The runtime always returns a non-empty string. The override
+  # tightens the call-site result to non-empty-string and tells
+  # the body's `assert_type` that `id` cannot be "".
+  %a{rigor:v1:return: non-empty-string}
+  %a{rigor:v1:param: id is non-empty-string}
+  def normalise: (::String id) -> ::String
+end
+```
+
+Right-hand side accepts:
+
+- **RBS class names** — `String`, `::Foo::Bar` (with optional
+  `~T` negation for `assert` / `predicate-if-*`).
+- **Imported-built-in refinement names** (kebab-case):
+  - Point-removal — `non-empty-string`, `non-zero-int`,
+    `non-empty-array[T]`, `non-empty-hash[K, V]`.
+  - IntegerRange aliases — `positive-int`, `non-negative-int`,
+    `negative-int`, `non-positive-int`, `int<min, max>`.
+  - Predicate refinements — `lowercase-string`,
+    `uppercase-string`, `numeric-string`, `decimal-int-string`,
+    `octal-int-string`, `hex-int-string`.
+  - Composed shapes — `non-empty-lowercase-string`,
+    `non-empty-uppercase-string`.
+
+The full directive table is in
+[`docs/type-specification/rbs-extended.md`](docs/type-specification/rbs-extended.md);
+the catalogue of refinement names is in
+[`docs/type-specification/imported-built-in-types.md`](docs/type-specification/imported-built-in-types.md).
+
+### Example: argument-type-mismatch caught at the call site
+
+```rbs
+# sig/normaliser.rbs
+class Normaliser
+  %a{rigor:v1:param: id is non-empty-string}
+  def normalise: (::String id) -> ::String
+end
+```
+
+```ruby
+# app/normaliser.rb
+class Normaliser
+  def normalise(id)
+    id.upcase
+  end
+end
+
+n = Normaliser.new
+n.normalise("hello")   # OK
+n.normalise("")        # rigor flags: argument type mismatch
+```
+
+`rigor check` reports the second call as an
+`argument-type-mismatch` because the literal `""` does not
+satisfy `non-empty-string`. Inside the method body, Rigor also
+sees `id` as `non-empty-string` (so `id.empty?` reduces to
+`Constant[false]` and `id.size` reduces to `positive-int`).
+
+## What rigor sees today
+
+- **Local / instance / class / global variables** —
+  intra-method bindings, cross-method ivar / cvar
+  accumulators, program-wide globals, and compound writes
+  (`||=`, `&&=`, `+=`).
+- **`self` typing and constant lookup** — class and method
+  body boundaries inject `Singleton[T]` / `Nominal[T]`;
+  lexical constant resolution walks RBS-core, common stdlib,
+  in-source class discovery, and in-source constant-value
+  tracking (`BUCKETS = [:a, :b]; BUCKETS.first` →
+  `Constant[:a]`).
 - **Predicate narrowing** — truthiness, `nil?`, `is_a?` /
   `kind_of?` / `instance_of?`, finite-literal equality,
   case-equality (`===`) for Class / Module / Range / Regexp,
   `case` / `when` integration.
-- **Blocks** — parameter binding (incl. destructuring + numbered
-  parameters), block-return-type uplift through generic methods
-  (`Array#map { |n| n.to_s }` → `Array[String]`), closure escape
-  classification, captured-local invalidation on escaping blocks.
 - **Tuple / HashShape carriers** — shape-aware element access,
-  range / start-length slices, closed / open / required / optional
-  policies threaded through `Acceptance`.
-- **`rigor check` first-preview rules** — undefined method on
-  typed receiver, wrong number of positional arguments. Both
-  consult RBS plus in-source `def` / `define_method` discovery so
-  reopened classes do not produce false positives.
-- **`RBS::Extended` annotation routes** —
-  `rigor:v1:return: <refinement>` overrides a method's RBS-declared
-  return; `rigor:v1:param: <name> [is] <refinement>` tightens a
-  parameter at both the call boundary and inside the method body;
-  `rigor:v1:assert <name> is <refinement>` substitutes the
-  refinement carrier at the post-call scope. The right-hand side
-  accepts any Capitalised class name OR a kebab-case refinement
-  payload from the imported-built-in catalogue (including
-  parameterised forms `non-empty-array[Integer]` and bounded
-  ranges `int<5, 10>`).
-
-See [docs/CURRENT_WORK.md](docs/CURRENT_WORK.md) for the canonical
-status snapshot, [docs/internal-spec/inference-engine.md](docs/internal-spec/inference-engine.md)
-for the engine contract, and [docs/adr/](docs/adr/) for the
-decision records.
-
-## Project layout
-
-- `lib/rigor` — runtime library, type model, inference engine, CLI.
-- `lib/rigor/analysis` — `Runner`, `CheckRules`, `Diagnostic`,
-  `FactStore`.
-- `lib/rigor/inference` — `Scope`-driven typers, dispatchers, and
-  narrowing.
-- `sig` — RBS signatures for Rigor itself.
-- `spec` — RSpec test suite (1250+ examples).
-- `docs/adr` — architecture decision records.
-- `docs/internal-spec` — engine contracts.
-- `docs/type-specification` — type-language semantics.
-
-## Roadmap past first preview
-
-In rough priority order (see CURRENT_WORK.md for details):
-
-1. More `rigor check` rules (nil-call, type-incompatible writes,
-   unbound locals).
-2. `RBS::Extended` effect plumbing (`%a{rigor:v1:pure}`,
-   mutation / escape / call-timing effects).
-3. Diagnostic publication for `FallbackTracer` events.
-4. Plugin contribution layer.
+  range / start-length slices, closed / open / required /
+  optional policies.
+- **Constant folding** — aggressive arithmetic / string /
+  Symbol / Tuple-shaped `divmod` folding, cartesian fold over
+  `Union[Constant…]`, integer-range arithmetic
+  (`positive-int + 1` → `int<2, max>`), branch elision on
+  provably-truthy / falsey predicates.
+- **Built-in catalogues** — Numeric, String, Symbol, Array,
+  IO, File, Hash, Range, Set, Time. Each catalog drives the
+  fold dispatcher with per-class blocklists for indirect
+  mutators.
+- **Refinement carriers** — `Type::Difference`,
+  `Type::Refined`, `Type::Intersection` provide the
+  imported-built-in catalogue end-to-end through
+  `Builtins::ImportedRefinements`.
+- **`RBS::Extended` directive routes** — `return:`, `param:`
+  (call-site + body-side), `assert:` /
+  `predicate-if-(true|false)` accept refinement payloads.
+
+The full per-release surface lives in
+[`CHANGELOG.md`](CHANGELOG.md). The internal contracts the
+analyzer guarantees live under
+[`docs/internal-spec/`](docs/internal-spec/).
+
+## Configuration
+
+`rigor init` writes a starter `.rigor.yml`:
+
+```sh
+bundle exec rigor init           # fails if .rigor.yml exists
+bundle exec rigor init --force   # overwrite
+```
+
+The configuration is intentionally small in v0.0.x; see the
+generated file for the available knobs.
+
+## Status
+
+Current release: **`v0.0.4`** (the fourth preview). The
+analyzer is usable on real Ruby code today but the rule
+catalogue is deliberately narrow — Rigor's stance is to surface
+zero false positives while the inference surface stabilises.
+The roadmap is tracked in
+[`docs/MILESTONES.md`](docs/MILESTONES.md); release-by-release
+detail lives in [`CHANGELOG.md`](CHANGELOG.md).
+
+## Contributing
+
+See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the minimal
+`git clone` → green-tests path and a map of the spec / ADR /
+skill documentation contributors should know about.
 
 ## License
 
-Rigor is licensed under the Mozilla Public License Version 2.0.
-See [LICENSE](LICENSE).
+Mozilla Public License Version 2.0. See [`LICENSE`](LICENSE).

data/data/builtins/ruby_core/comparable.yml

@@ -0,0 +1,87 @@
+# DO NOT EDIT — generated by tool/extract_builtin_catalog.rb
+---
+schema_version: 1
+generated_from:
+  ruby_init_c: references/ruby/compar.c
+  ruby_prelude:
+  rbs:
+  - references/rbs/core/comparable.rbs
+purity_levels:
+  leaf: Prelude :leaf marker (VM-enforced) or C body uses no dispatch/yield/mutation.
+  trivial: Prelude method body is a literal return (self/true/false/nil/Integer).
+  leaf_when_numeric: C body falls through to rb_num_coerce_* only when an operand
+    is non-numeric; safe to fold when every argument is a concrete numeric.
+  inline_block: Prelude method carries :inline_block or :use_block; block-dependent.
+  block_dependent: C body yields or checks rb_block_given_p.
+  mutates_self: C body checks rb_check_frozen — typically a prelude to mutation.
+  dispatch: C body calls user-redefinable methods (rb_funcall*, rb_equal, rb_Float,
+    num_funcall*, etc).
+  unknown: C body not located in indexed C files.
+classes:
+  Comparable:
+    parent: Module
+    defined_at: references/ruby/compar.c:324
+    includes: []
+    constants: {}
+    aliases: {}
+    instance_methods:
+      "==":
+        source: c
+        cfunc: cmp_equal
+        arity: 1
+        defined_at: references/ruby/compar.c:325
+        c_body_at: references/ruby/compar.c:79
+        c_effects:
+        - dispatch
+        purity: dispatch
+      ">":
+        source: c
+        cfunc: cmp_gt
+        arity: 1
+        defined_at: references/ruby/compar.c:326
+        c_body_at: references/ruby/compar.c:105
+        c_effects: []
+        purity: leaf
+      ">=":
+        source: c
+        cfunc: cmp_ge
+        arity: 1
+        defined_at: references/ruby/compar.c:327
+        c_body_at: references/ruby/compar.c:119
+        c_effects: []
+        purity: leaf
+      "<":
+        source: c
+        cfunc: cmp_lt
+        arity: 1
+        defined_at: references/ruby/compar.c:328
+        c_body_at: references/ruby/compar.c:137
+        c_effects: []
+        purity: leaf
+      "<=":
+        source: c
+        cfunc: cmp_le
+        arity: 1
+        defined_at: references/ruby/compar.c:329
+        c_body_at: references/ruby/compar.c:156
+        c_effects: []
+        purity: leaf
+      between?:
+        source: c
+        cfunc: cmp_between
+        arity: 2
+        defined_at: references/ruby/compar.c:330
+        c_body_at: references/ruby/compar.c:177
+        c_effects: []
+        purity: leaf
+      clamp:
+        source: c
+        cfunc: cmp_clamp
+        arity: -1
+        defined_at: references/ruby/compar.c:331
+        c_body_at: references/ruby/compar.c:231
+        c_effects:
+        - raises
+        purity: leaf
+    singleton_methods: {}
+    undefined: []