rigortype 0.0.8 → 0.0.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 38aa66f97f5bed742a36c156ceee7f13d3181597b74c32329b693b3c219852b3
-  data.tar.gz: 69af0ccbf42c2b890b78a558d574b49293ff6b4880875568137098624e66d3f8
+  metadata.gz: b054649005dbeb85c95236ebfba7fe7540e52c10c60aff095fbce81d5b589d67
+  data.tar.gz: 9d879aa46bf37164f52f31786bade4d0ede52203d140cf0a2b1571f23160cd7d
 SHA512:
-  metadata.gz: 8a9e0ee0461e2f0b2779981fa95758e0b7b5bd02668254dc1cb2d82002565b383d866534edff6e75c53aa0a9ae2fdb59832a35788ccfda3cb4558982bed61b15
-  data.tar.gz: 9699b63098d16e1959177684a849923384196f0dac55a532a3a0ecdff77d45c76230c3b72a273f59ec237059127007d7bb1ae01be9c9cf8b9613a02033b89bb5
+  metadata.gz: ae684fc0749faa78117d85c75550b19e6a8e83b53172feea275d9ae1d804cec4f77d187b7ea4ae66e3035ed722bca0636622785f8537a3c42c9eb4ed9dc10b90
+  data.tar.gz: 340b93e08cfcbf7050d6f908aa16e0508250df0cf0d727fb7f5a81f02b312248ee62e403d0046d2c8230cfb71821f4c64d63634bed3eeec276105ad4e663be17

data/README.md

@@ -14,14 +14,23 @@ 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`, …).
 
+The differentiator is a richer type vocabulary than ordinary
+RBS expresses. Rigor reasons about *what values an expression
+actually produces* — literal values, integer ranges,
+refinement-type carriers, per-position tuple / hash shapes —
+not just *which class an object belongs to*. See **[Beyond
+`Integer` and `String`](#beyond-integer-and-string-rigors-richer-type-vocabulary)**
+for the full type-model story; the short pitch is below.
+
 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.
+`positive-int`, `non-empty-array[Integer]`, `int<5, 10>`,
+`literal-string`, `non-lowercase-string`, …) without changing
+the underlying RBS.
 
 ## Installation
 
@@ -51,7 +60,7 @@ The gem ships an executable named `rigor` (gem name is
 
 **Ruby version.** The gemspec requires `>= 4.0.0, < 4.1`.
 
-## First analysis
+## Quick start
 
 Drop into your project root and run the canonical commands:
 
@@ -60,15 +69,15 @@ Drop into your project root and run the canonical commands:
 # rule-driven bugs across `lib/`.
 bundle exec rigor check lib
 
+# Drop a starter .rigor.yml into the project root.
+bundle exec rigor init
+
 # Print the inferred type at a precise FILE:LINE:COL position.
 bundle exec rigor type-of lib/foo.rb:10:5
 
 # 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
-
-# Drop a starter .rigor.yml into the project root.
-bundle exec rigor init
 ```
 
 ### Sample output
@@ -90,6 +99,124 @@ 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.
 
+### Faster runs through the cache
+
+Rigor caches expensive RBS work (the loaded `RBS::Environment`,
+constant-type translation, class hierarchy, type-parameter
+names, known-class set) under `.rigor/cache/` so the second
+`rigor check` is significantly faster than the first. The cache
+is keyed by your project's `.rbs` file digests + the locked
+`rbs` gem version, so a signature change or a gem upgrade
+invalidates exactly what it should.
+
+```sh
+# Inspect what is cached on disk and what this run did.
+bundle exec rigor check --cache-stats lib
+
+# Wipe the cache (do this if you suspect staleness).
+bundle exec rigor check --clear-cache lib
+
+# Run with caching disabled.
+bundle exec rigor check --no-cache lib
+```
+
+Add `.rigor/` to your `.gitignore` — the cache is per-checkout
+and contains nothing reproducible to share.
+
+## Beyond `Integer` and `String`: Rigor's richer type vocabulary
+
+A vanilla static checker answers "what *class* is this object?"
+Rigor answers a much narrower question: "what *subset of values*
+can this expression actually produce?" That distinction is the
+whole point of Rigor — types like `Integer` and `String` describe
+classes, but real-world code carries far more structure (a count
+that's always non-negative, a name that's never empty, a flag
+that's one of three Symbols). Rigor reasons about that structure
+out of the box, without you writing a single annotation.
+
+### The carrier zoo
+
+| Carrier | What it records | Example |
+| --- | --- | --- |
+| **Literal types** (`Type::Constant`) | A single Ruby value | `Constant<42>`, `Constant<"hello">`, `Constant<:foo>` |
+| **Integer ranges** (`Type::IntegerRange`) | A bounded integer interval `int<a, b>` | `positive-int = int<1, max>`, `int<5, 10>` |
+| **Refinement types** — split into two halves: `Type::Difference` and `Type::Refined` | A base nominal minus a single value, or a base nominal restricted by a predicate | `non-empty-string = String - ""`, `lowercase-string = String & lowercase?`, `literal-string` |
+| **Intersection** (`Type::Intersection`) | Composition of multiple refinements | `non-empty-lowercase-string = non-empty-string ∩ lowercase-string` |
+| **Tuple / HashShape** | Heterogeneous arrays / known-key hashes that carry per-position / per-key types | `[1, "two", :three]` types as `Tuple[Constant<1>, Constant<"two">, Constant<:three>]`; `{name: "Alice", age: 30}` as `HashShape{name: Constant<"Alice">, age: Constant<30>}` |
+| **Union** (`Type::Union`) | "One of these literal values" — finite enums Rigor can enumerate | `Constant<:zero> \| Constant<:small> \| Constant<:large>` |
+| **`Dynamic[T]`** | The gradual carrier — wraps a static facet with a "could be anything" admission | `Dynamic[Top]` is the conservative fallback Rigor uses when it cannot prove a narrower type |
+
+Each refinement / range / literal carrier **erases to its base
+class** for ordinary RBS interop, so importing Rigor is a
+strictly additive change: a method whose RBS sig says
+`-> String` keeps that contract, and Rigor's narrower inference
+just sits on top.
+
+### What this buys you in practice
+
+```ruby
+# Rigor doesn't just see "Integer", it sees "non-negative integer".
+n = ARGV.size                  # int<0, max>  (non-negative-int)
+m = n + 1                      # int<1, max>  (positive-int)
+m.zero?                        # Constant<false>  — proven; the
+                               # branch elision can drop the `else`
+
+# String composition stays as precise as the inputs allow.
+greeting = "Hello, "           # Constant<"Hello, ">
+name     = ARGV.first          # String?       — RBS-declared
+hello    = "Hello, #{name}!"   # literal-string — every part is
+                               # literal-bearing, so the result is
+                               # provably source-derived.
+
+# Tuple-shaped destructuring stays per-position.
+first, _middle, last = [10, 20, 30]
+first                          # Constant<10>
+last                           # Constant<30>
+
+# Constant folding through user methods.
+def is_odd(n) = n.odd?
+is_odd(3)                      # Constant<true>  — folded through
+                               # the body, not just typed as `bool`
+
+# Case/when narrowing produces a literal-set Union.
+label = case n
+        when 0      then :zero
+        when 1..9   then :small
+        else             :large
+        end
+label                          # Constant<:zero> | Constant<:small>
+                               #   | Constant<:large>
+
+# RBS::Extended directives let you tighten beyond what RBS expresses.
+class Slug
+  %a{rigor:v1:return: non-empty-string}
+  def normalise: (::String id) -> ::String
+end
+Slug.new.normalise("foo").size  # positive-int  — provably ≥ 1
+```
+
+Rigor never invents these answers — every narrower carrier is
+derived from literals in the source, control-flow narrowing
+(`is_a?`, `nil?`, `==` against finite literal sets, integer
+comparisons), per-class catalogues for the bundled built-ins,
+or `RBS::Extended` directives the user opted into. When the
+inference cannot prove a value is in a narrower carrier, it
+stays at the wider one (or `Dynamic[Top]`) and Rigor stays
+silent — diagnostics fire only when the narrow type is
+genuinely proved.
+
+### Where the type model is documented
+
+- One-page mental model:
+  [`docs/types.md`](docs/types.md).
+- Binding spec corpus:
+  [`docs/type-specification/`](docs/type-specification/README.md).
+- Imported refinement names (kebab-case catalogue):
+  [`docs/type-specification/imported-built-in-types.md`](docs/type-specification/imported-built-in-types.md).
+- The `RBS::Extended` annotation grammar that opens this
+  vocabulary up to your own RBS:
+  [`docs/type-specification/rbs-extended.md`](docs/type-specification/rbs-extended.md).
+
 ## How Rigor finds your types
 
 Rigor consults, in order:
@@ -102,8 +229,9 @@ Rigor consults, in order:
 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.
+   Rigor walks `def` / `define_method` / `attr_*` /
+   `Data.define(*Symbol)` 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
@@ -139,8 +267,17 @@ Right-hand side accepts:
   - Predicate refinements — `lowercase-string`,
     `uppercase-string`, `numeric-string`, `decimal-int-string`,
     `octal-int-string`, `hex-int-string`.
+  - Paired complements (`~T`-symmetric) —
+    `non-lowercase-string`, `non-uppercase-string`,
+    `non-numeric-string`. Writing `~lowercase-string` narrows
+    `String` to `non-lowercase-string` instead of the generic
+    `Difference[String, lowercase-string]` fallback.
   - Composed shapes — `non-empty-lowercase-string`,
-    `non-empty-uppercase-string`.
+    `non-empty-uppercase-string`, `non-empty-literal-string`.
+  - Flow-tracked source-literal — `literal-string`. Rigor lifts
+    `"hi #{name}!"`, `"a" + literal_str`, and `literal_str * 3`
+    to `literal-string` when every operand is itself
+    literal-bearing.
 
 The full directive table is in
 [`docs/type-specification/rbs-extended.md`](docs/type-specification/rbs-extended.md);
@@ -191,26 +328,38 @@ sees `id` as `non-empty-string` (so `id.empty?` reduces to
 - **Predicate narrowing** — truthiness, `nil?`, `is_a?` /
   `kind_of?` / `instance_of?`, finite-literal equality,
   case-equality (`===`) for Class / Module / Range / Regexp,
-  `case` / `when` integration.
+  `case` / `when` integration. Paired-complement narrowing for
+  Refined predicates (`~lowercase-string` →
+  `non-lowercase-string`).
 - **Tuple / HashShape carriers** — shape-aware element access,
   range / start-length slices, closed / open / required /
-  optional policies.
+  optional policies, per-element block fold over
+  `map`, `select`, `filter_map`, `flat_map`, `find` /
+  `find_index`, `count`, `any?` / `all?` / `none?`, `zip`.
 - **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.
+  provably-truthy / falsey predicates,
+  `Constant<String>#%` format-string fold against
+  `Tuple` / `HashShape` arguments.
+- **Built-in catalogues** — Numeric / Integer / Float, String /
+  Symbol, Array, Hash, IO, File, Range, Set, Time, Date /
+  DateTime, Comparable, Enumerable, Rational, Complex,
+  Pathname, Random, Struct (+ `Data`), Encoding, Regexp /
+  MatchData, Proc / Method / UnboundMethod, Exception. 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.
+  `predicate-if-(true|false)` accept refinement payloads, and
+  roll up into a single `Rigor::FlowContribution` bundle per
+  method (the v0.1.0 plugin contribution merger reads bundles
+  directly).
 
 The full per-release surface lives in
 [`CHANGELOG.md`](CHANGELOG.md). The internal contracts the
@@ -226,19 +375,42 @@ 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.
+Common knobs the file exposes:
+
+- `paths` — directories `rigor check` and `rigor type-scan`
+  scan when no path is given (defaults to `lib`).
+- `target_ruby` — minimum Ruby version your project targets.
+- `libraries` — extra stdlib libraries to load on top of the
+  bundled defaults (e.g. `["csv", "set"]`).
+- `signature_paths` — explicit list of `sig/`-style directories.
+  Leave unset (or `null`) to auto-detect `<root>/sig`. Use `[]`
+  to disable project-RBS loading entirely.
+- `disable` — rule identifiers to silence project-wide. Shipped
+  rules: `undefined-method`, `wrong-arity`,
+  `argument-type-mismatch`, `possible-nil-receiver`,
+  `dump-type`, `assert-type`, `always-raises`. In-source
+  `# rigor:disable <rule>` end-of-line comments silence
+  per-line; `# rigor:disable all` suppresses every rule.
 
 ## Status
 
-Current release: **`v0.0.4`** (the fourth preview). The
-analyzer is usable on real Ruby code today but the rule
+Current released version: **`v0.0.8`** (the eighth 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).
 
+`v0.0.9` is the active development cluster on `master` and
+covers the persistent cache infrastructure (`.rigor/cache/`,
+`--cache-stats`, `--clear-cache`, `--no-cache`),
+paired-complement Refined narrowing, `literal-string` flow
+tracking, the `Rigor::FlowContribution` bundle struct, and
+six additional built-in catalogues (Random, Struct, Encoding,
+Regexp + MatchData, Proc / Method / UnboundMethod, Exception).
+The next release after `0.0.9` will be `0.1.0`.
+
 ## Contributing
 
 See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the minimal
@@ -248,3 +420,5 @@ skill documentation contributors should know about.
 ## License
 
 Mozilla Public License Version 2.0. See [`LICENSE`](LICENSE).
+</content>
+</invoke>

data/data/builtins/ruby_core/encoding.yml

@@ -0,0 +1,210 @@
+# DO NOT EDIT — generated by tool/extract_builtin_catalog.rb
+---
+schema_version: 1
+generated_from:
+  ruby_init_c: references/ruby/encoding.c
+  ruby_prelude:
+  rbs:
+  - references/rbs/core/encoding.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:
+  Encoding:
+    parent: Object
+    defined_at: references/ruby/encoding.c:1992
+    includes: []
+    constants: {}
+    aliases:
+      to_s:
+        old: name
+        source: c
+        defined_at: references/ruby/encoding.c:2001
+    instance_methods:
+      inspect:
+        source: c
+        cfunc: enc_inspect
+        arity: 0
+        defined_at: references/ruby/encoding.c:2003
+        c_body_at: references/ruby/encoding.c:1344
+        c_effects:
+        - raises
+        purity: leaf
+        rbs:
+        - "() -> String"
+        rbs_at: references/rbs/core/encoding.rbs:281
+      names:
+        source: c
+        cfunc: enc_names
+        arity: 0
+        defined_at: references/ruby/encoding.c:2004
+        c_body_at: references/ruby/encoding.c:1384
+        c_effects: []
+        purity: leaf
+        rbs:
+        - "() -> Array[String]"
+        rbs_at: references/rbs/core/encoding.rbs:298
+      dummy?:
+        source: c
+        cfunc: enc_dummy_p
+        arity: 0
+        defined_at: references/ruby/encoding.c:2005
+        c_body_at: references/ruby/encoding.c:663
+        c_effects: []
+        purity: leaf
+        rbs:
+        - "() -> bool"
+        rbs_at: references/rbs/core/encoding.rbs:270
+      ascii_compatible?:
+        source: c
+        cfunc: enc_ascii_compatible_p
+        arity: 0
+        defined_at: references/ruby/encoding.c:2006
+        c_body_at: references/ruby/encoding.c:679
+        c_effects: []
+        purity: leaf
+        rbs:
+        - "() -> bool"
+        rbs_at: references/rbs/core/encoding.rbs:257
+      _dump:
+        source: c
+        cfunc: enc_dump
+        arity: -1
+        defined_at: references/ruby/encoding.c:2013
+        c_body_at: references/ruby/encoding.c:1502
+        c_effects: []
+        purity: leaf
+    singleton_methods:
+      list:
+        source: c
+        cfunc: enc_list
+        arity: 0
+        defined_at: references/ruby/encoding.c:2007
+        c_body_at: references/ruby/encoding.c:1416
+        c_effects: []
+        purity: leaf
+        rbs:
+        - "() -> Array[Encoding]"
+        rbs_at: references/rbs/core/encoding.rbs:232
+      name_list:
+        source: c
+        cfunc: rb_enc_name_list
+        arity: 0
+        defined_at: references/ruby/encoding.c:2008
+        c_body_at: references/ruby/encoding.c:1895
+        c_effects: []
+        purity: leaf
+        rbs:
+        - "() -> Array[String]"
+        rbs_at: references/rbs/core/encoding.rbs:246
+      aliases:
+        source: c
+        cfunc: rb_enc_aliases
+        arity: 0
+        defined_at: references/ruby/encoding.c:2009
+        c_body_at: references/ruby/encoding.c:1941
+        c_effects: []
+        purity: leaf
+        rbs:
+        - "() -> Hash[String, String]"
+        rbs_at: references/rbs/core/encoding.rbs:66
+      find:
+        source: c
+        cfunc: enc_find
+        arity: 1
+        defined_at: references/ruby/encoding.c:2010
+        c_body_at: references/ruby/encoding.c:1445
+        c_effects: []
+        purity: leaf
+        rbs:
+        - "(encoding enc) -> Encoding?"
+        rbs_at: references/rbs/core/encoding.rbs:213
+      compatible?:
+        source: c
+        cfunc: enc_compatible_p
+        arity: 2
+        defined_at: references/ruby/encoding.c:2011
+        c_body_at: references/ruby/encoding.c:1480
+        c_effects: []
+        purity: leaf
+        rbs:
+        - "(untyped obj1, untyped obj2) -> Encoding?"
+        rbs_at: references/rbs/core/encoding.rbs:91
+      _load:
+        source: c
+        cfunc: enc_load
+        arity: 1
+        defined_at: references/ruby/encoding.c:2014
+        c_body_at: references/ruby/encoding.c:1510
+        c_effects: []
+        purity: leaf
+        rbs:
+        - "[T] (T) -> T"
+        rbs_at: references/rbs/core/encoding.rbs:30
+      default_external:
+        source: c
+        cfunc: get_default_external
+        arity: 0
+        defined_at: references/ruby/encoding.c:2016
+        c_body_at: references/ruby/encoding.c:1704
+        c_effects: []
+        purity: leaf
+        rbs:
+        - "() -> Encoding"
+        rbs_at: references/rbs/core/encoding.rbs:121
+      default_external=:
+        source: c
+        cfunc: set_default_external
+        arity: 1
+        defined_at: references/ruby/encoding.c:2017
+        c_body_at: references/ruby/encoding.c:1733
+        c_effects: []
+        purity: leaf
+        rbs:
+        - "(Encoding enc) -> Encoding"
+        - "[T < _ToStr] (T enc) -> T"
+        rbs_at: references/rbs/core/encoding.rbs:135
+      default_internal:
+        source: c
+        cfunc: get_default_internal
+        arity: 0
+        defined_at: references/ruby/encoding.c:2018
+        c_body_at: references/ruby/encoding.c:1787
+        c_effects: []
+        purity: leaf
+        rbs:
+        - "() -> Encoding?"
+        rbs_at: references/rbs/core/encoding.rbs:166
+      default_internal=:
+        source: c
+        cfunc: set_default_internal
+        arity: 1
+        defined_at: references/ruby/encoding.c:2019
+        c_body_at: references/ruby/encoding.c:1813
+        c_effects: []
+        purity: leaf
+        rbs:
+        - "(Encoding enc) -> Encoding"
+        - "[T < _ToStr] (T enc) -> T"
+        - "(nil) -> nil"
+        rbs_at: references/rbs/core/encoding.rbs:181
+      locale_charmap:
+        source: c
+        cfunc: rb_locale_charmap
+        arity: 0
+        defined_at: references/ruby/encoding.c:2020
+        purity: unknown
+        c_body_at: not_found
+        rbs:
+        - "() -> String"
+        rbs_at: references/rbs/core/encoding.rbs:54
+    undefined:
+    - new