rigortype 0.2.1 → 0.2.2

data/docs/manual/plugins/rigor-dry-types.md

@@ -0,0 +1,59 @@
+# rigor-dry-types
+
+The foundation plugin for the dry-rb family. It recognises the
+canonical dry-types alias module —
+
+```ruby
+module Types
+  include Dry.Types()
+end
+```
+
+— and makes the alias names it generates resolvable to their
+underlying Ruby classes, publishing them as a cross-plugin fact
+(`:dry_type_aliases`) that [`rigor-dry-struct`](../07-plugins.md),
+`rigor-dry-schema`, and `rigor-dry-validation` consume.
+
+It ships bundled in `rigortype`. Activate it alongside the dry-rb
+plugins that consume it:
+
+```yaml
+plugins:
+  - rigor-dry-types
+  - rigor-dry-struct
+  # - rigor-dry-schema / rigor-dry-validation as needed
+```
+
+## No diagnostics of its own
+
+This plugin emits **no diagnostics** and has **no config keys** —
+it only supplies type information to the other dry-rb plugins, so
+its visible effect surfaces through them (a `Types::String`-typed
+attribute resolving downstream, etc.).
+
+## What it recognises
+
+- **Canonical shortcuts** — `Types::String` / `Integer` / `Float` /
+  `Decimal` → `BigDecimal` / `Bool` / `Date` / `Hash` / `Array` /
+  `Any` → `Object`, and the rest.
+- **Coercion-category namespaces** — the same names under
+  `Coercible::` / `Strict::` / `Params::` / `JSON::` (they share an
+  underlying class; the difference is runtime coercion).
+- **Nested alias modules** — `module App; module Types; include
+  Dry.Types(); end; end` publishes `App::Types::String`, etc.
+- **User-authored single-head compositions** — `Email =
+  String.constrained(format: …)`, `Status = Strict::Symbol`,
+  `PositiveInt = Integer.constrained(gt: 0).optional` publish under
+  the head's underlying class.
+
+Unions (`String | Integer`), intersections, and transitive
+references to other compositions (`ManagerEmail = Email`) are
+skipped — there's no single underlying class to publish.
+
+## Plugin internals
+
+The `prepare(services)` scan, the published `:dry_type_aliases`
+table, and the slice floor/ceiling are documented in the
+[plugin's README](../../../plugins/rigor-dry-types/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-dry-validation.md

@@ -0,0 +1,62 @@
+# rigor-dry-validation
+
+Recognises `class T < Dry::Validation::Contract` subclasses,
+publishes the set of contract class names as a cross-plugin fact
+(`:dry_validation_contracts`), and ships an RBS overlay typing the
+contract result API (`Contract#call → Result`, then `Result#success?`
+/ `#failure?` / `#to_h` / `#errors` / `#[]`).
+
+It ships bundled in `rigortype`. Activate it under `plugins:`:
+
+```yaml
+plugins:
+  - rigor-dry-validation
+```
+
+## What it recognises
+
+```ruby
+class NewUserContract < Dry::Validation::Contract
+  params do
+    required(:email).filled(:string)
+    required(:age).value(:integer)
+  end
+end
+```
+
+The plugin recognises both the full-path
+`Dry::Validation::Contract` and the lexical-`Dry` form
+`Validation::Contract`, and publishes a sorted list of the
+discovered contract names.
+
+With the RBS overlay loaded (see below):
+
+```ruby
+result = NewUserContract.new.call(input)  # Dry::Validation::Result
+result.success?                            # bool
+result.to_h                                # Hash[Symbol, untyped]
+```
+
+## RBS overlay
+
+The plugin bundles an RBS overlay (`sig/dry_validation.rbs`) that
+types the result API above, and **contributes it automatically** —
+the plugin's manifest declares `signature_paths: ["sig"]`
+([ADR-25](../../adr/25-plugin-contributed-rbs.md)), so activating
+`rigor-dry-validation` is enough; no project-side `signature_paths:`
+wiring is required.
+
+## No diagnostics, no config
+
+The plugin publishes the contract list and the overlay; it emits no
+diagnostics and takes no config keys. (Future slices add
+`result.to_h` typing from a paired `rigor-dry-schema` `params` block
+and per-contract `rule`-key diagnostics.)
+
+## Plugin internals
+
+The `prepare(services)` scan, the `:dry_validation_contracts` fact,
+the RBS overlay, and the slice floor/ceiling are documented in the
+[plugin's README](../../../plugins/rigor-dry-validation/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-factorybot.md

@@ -0,0 +1,76 @@
+# rigor-factorybot
+
+Validates every `FactoryBot.create(:name, key: …)` / `.build(…)` /
+`.build_stubbed(…)` / `.attributes_for(…)` / `*_list` call against
+an index of your factory definitions: an unknown factory name or an
+attribute key the factory doesn't declare is flagged (each with a
+did-you-mean). When [`rigor-activerecord`](rigor-activerecord.md) is
+also active, attribute keys are additionally cross-checked against
+the model's columns. No FactoryBot runtime dependency.
+
+It ships bundled in `rigortype`. Activate it under `plugins:`:
+
+```yaml
+plugins:
+  - rigor-factorybot
+  # - rigor-activerecord   # optional: enables the AR column cross-check
+```
+
+## What it checks
+
+```ruby
+# spec/factories/users.rb
+FactoryBot.define do
+  factory :user do
+    name  { "Alice" }
+    email { "alice@example.com" }
+  end
+end
+
+FactoryBot.create(:user, name: "X")     # ✓ info trace
+FactoryBot.build(:post, headline: "Hi") # ✗ unknown-attribute (suggest :title)
+FactoryBot.create(:usre)                # ✗ unknown-factory (suggest :user)
+```
+
+| Rule | Severity | Fires when |
+| --- | --- | --- |
+| `plugin.factorybot.factory-call` | info | the call resolved to a known factory; lists its declared attributes |
+| `plugin.factorybot.unknown-factory` | error | the literal `:name` isn't in the factory index (with a did-you-mean) |
+| `plugin.factorybot.unknown-attribute` | error | a keyword key isn't a declared attribute (with a did-you-mean); also checked against the model's columns when `:model_index` is available |
+
+The legacy `FactoryGirl` constant is recognised the same way.
+Recognised entry methods: `create` / `build` / `build_stubbed` /
+`attributes_for` and the `*_list` variants. Inside a factory it
+recognises `name { … }` (modern), `name "…"` (legacy positional),
+and `add_attribute(:name) { … }`.
+
+## Configuration
+
+```yaml
+plugins:
+  - gem: rigor-factorybot
+    config:
+      factory_search_paths: ["spec/factories", "spec/factories.rb"]  # default
+      # Minitest projects: ["test/factories"]
+```
+
+## Limitations
+
+- **Literal arguments only** — `FactoryBot.create(name)` with a
+  variable name passes through.
+- **Traits / sequences / associations not collected yet** — an
+  attribute defined only inside `trait :admin do … end` can surface
+  a false `unknown-attribute` until the trait slice ships.
+- **Explicit receiver only** — bare `create(:user)` (from
+  `include FactoryBot::Syntax::Methods`) is not recognised in this
+  slice; it needs receiver-type inference, which would otherwise
+  false-positive on every unrelated `create` call.
+
+## Plugin internals
+
+The factory discoverer / index, the cached producer, the
+`:model_index` consumption, the demo, and the contract surfaces
+this plugin exercises are in the
+[plugin's README](../../../plugins/rigor-factorybot/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-graphql.md

@@ -0,0 +1,89 @@
+# rigor-graphql
+
+Recognises GraphQL-Ruby schema classes — `Schema::Object`,
+`Schema::Enum`, `Schema::InputObject`, `Schema::Mutation` subclasses —
+and walks their `field` / `value` / `argument` DSL declarations,
+publishing the resulting type tables as
+[ADR-9](../../adr/9-cross-plugin-api.md) cross-plugin facts that
+downstream plugins can consume. graphql-ruby's `field` DSL is a pure
+metadata recorder (it synthesises no Ruby methods), so Rigor's value
+here is a static type table rather than method synthesis. It reads
+source only, with no `graphql` runtime dependency.
+
+It ships bundled in `rigortype`. Activate it under `plugins:`:
+
+```yaml
+plugins:
+  - rigor-graphql
+```
+
+## What it infers
+
+```ruby
+module Types
+  class User < GraphQL::Schema::Object
+    field :name, String, null: false
+    field :email, String, null: true
+    field :tags, [String], null: false   # list-of form
+  end
+end
+```
+
+publishes a `:graphql_type_table` fact:
+
+```ruby
+{
+  "Types::User" => {
+    "name"  => { type: "String", nullable: false, list: false },
+    "email" => { type: "String", nullable: true,  list: false },
+    "tags"  => { type: "String", nullable: false, list: true }
+  }
+}
+```
+
+It publishes four independent facts from one project walk; consumers
+that need only one (or none) are unaffected by the others:
+
+| Fact | Source class | Shape |
+| --- | --- | --- |
+| `:graphql_type_table` | `Schema::Object` | `field` → `{type, nullable, list}` |
+| `:graphql_enum_table` | `Schema::Enum` | `value "..."` → ordered value list |
+| `:graphql_input_object_table` | `Schema::InputObject` | `argument` → `{type, required, list}` |
+| `:graphql_mutation_table` | `Schema::Mutation` | `{arguments:, fields:}` combined |
+
+Canonical GraphQL scalars map to Ruby classes (`String`→`String`,
+`Integer`/`Int`→`Integer`, `Boolean`→`TrueClass`, `Float`→`Float`,
+`ID`→`String`); user-defined types are recorded under their qualified
+name. `null:` extracts to `nullable:` (defaulting to `true`, mirroring
+graphql-ruby); `required:` defaults to `false`. The single-element
+`[String]` list form is recognised.
+
+## No diagnostics, no config
+
+The plugin emits no diagnostics and has no configuration knobs — it
+contributes the type tables above for other plugins to consume. It
+walks every `paths:` entry's `.rb` files for the schema-class shapes.
+
+## Limitations
+
+- **No resolver-method type-check.** `field` declarations are recorded
+  as metadata; they are not yet cross-referenced against the Ruby
+  resolver methods that back them.
+- **No `Schema.execute(...)` result typing.** Typing
+  `Schema.execute(query).to_h` against the queried fields is a future
+  plugin.
+- **Constant-form types only.** The string form (`field :foo, "User"`)
+  and the `<Type>.array` / `<Type>!` sugar chains are not recognised
+  (the `[String]` bracket form is). Multi-element and empty list
+  literals are dropped.
+- **Enum literal values only.** `value "ACTIVE"` registers; the
+  symbol-form (`value :ACTIVE`) and constant-form drop, and the
+  `value:` / `description:` kwargs ride along but stay out of the table.
+- **No cache round-trip** — the walk re-runs each invocation.
+
+## Plugin internals
+
+The type scanner and the contract surfaces this plugin exercises are in
+the [plugin's README](../../../plugins/rigor-graphql/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-hanami.md

@@ -0,0 +1,83 @@
+# rigor-hanami
+
+Enforces the **Hanami::Action protocol** for Hanami 3.x apps: every
+class under `app/actions/**/*.rb` must define `#handle(request,
+response)`, and inside those bodies Rigor types the two parameters as
+`Hanami::Action::Request` / `Hanami::Action::Response` so misuse is
+caught precisely. It is the reference production consumer of the
+[ADR-28](../../adr/28-path-scoped-protocol-contracts.md) path-scoped
+method-protocol contract — Rigor *provides* the parameter types and the
+plugin *checks* the method shape. It reads source only, with no
+`hanami` runtime dependency (it ships RBS stubs for the Request /
+Response / Params surface).
+
+It ships bundled in `rigortype`. Activate it under `plugins:`:
+
+```yaml
+plugins:
+  - rigor-hanami
+```
+
+## What it checks
+
+```ruby
+# app/actions/books/index.rb
+module Bookshelf
+  module Actions
+    module Books
+      class Index < Bookshelf::Action
+        def handle(request, response)
+          response.status = 200                 # response: Hanami::Action::Response
+          response.body = request.params[:q]    # request: Hanami::Action::Request
+          request.no_such_method                # error: call.undefined-method
+        end
+      end
+    end
+  end
+end
+```
+
+| Rule | Severity | Fires when |
+| --- | --- | --- |
+| `plugin.hanami.missing-handle-method` | error | a class in a matching file defines no `#handle` |
+| `plugin.hanami.handle-arity-mismatch` | error | `#handle` is defined with a parameter count other than 2 |
+
+Inside a conforming `#handle`, misuse of `request` / `response`
+surfaces as the engine's own `call.undefined-method` — the same as if
+the types had been declared in RBS. Return-type conformance is *not*
+checked: `#handle` is void by contract (the response is mutated
+in-place), so checking the return value would generate false positives
+on every conditional branch. Parameter names are arbitrary (positions,
+not names, are bound); only directly-defined `#handle` is checked, not
+an inherited one.
+
+## Configuration
+
+```yaml
+plugins:
+  - gem: rigor-hanami
+    config:
+      action_path: "app/actions/**/*.rb"   # default
+```
+
+Override `action_path` for a custom slice layout, e.g.
+`"slices/main/actions/**/*.rb"`. The override retargets both the
+parameter-type provision and the `#handle` check.
+
+## Limitations
+
+- **Exact arity.** `#handle` must take exactly two parameters; optional
+  or keyword-only forms are flagged as `handle-arity-mismatch`.
+- **Direct definition only.** A `#handle` inherited from a base class
+  (rather than defined on the class itself) is not detected.
+- **Stubbed surface.** The bundled RBS covers the documented Request /
+  Response / Params methods; calls outside that surface resolve against
+  the stubs, not a live Hanami install.
+
+## Plugin internals
+
+The `ProtocolContract` declaration, the action checker, the RBS stubs,
+and the ADR-28 provide-and-check split are in the
+[plugin's README](../../../plugins/rigor-hanami/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-mangrove.md

@@ -0,0 +1,73 @@
+# rigor-mangrove
+
+Sharpens [Mangrove](https://github.com/) `Result` / `Option`
+unwrap-family return types from `untyped` to the concrete
+type-argument carried at the call site, and synthesises the
+subclasses an `Enum`'s `variants do … end` DSL generates at runtime
+so they resolve statically. It layers on top of
+[`rigor-sorbet`](rigor-sorbet.md) (which ingests Mangrove's `sig` /
+RBI surface); this plugin adds the two precision steps sig-level
+types can't reach. No runtime dependency.
+
+It ships bundled in `rigortype`. Activate it under `plugins:`
+(alongside `rigor-sorbet`, which supplies the carrier types):
+
+```yaml
+plugins:
+  - rigor-sorbet
+  - rigor-mangrove
+```
+
+## What it infers — no diagnostics, no config
+
+The plugin emits no diagnostics of its own and has no
+configuration. It contributes types in two places; the engine's
+ordinary method-existence check then catches typos on the
+now-known types.
+
+**Unwrap-family return types.** When the receiver is a Mangrove
+carrier carrying a type argument, the unwrap return narrows to that
+argument:
+
+```ruby
+# token : Result::Ok[String, StandardError]
+session.token.unwrap!.uppercaze   # error: undefined method `uppercaze' for String
+```
+
+**Enum variant synthesis (ADR-36 Slice A).** The `variants` DSL
+emits nested subclasses at runtime; the plugin synthesises them
+statically — the variant constant resolves, `.new` dispatches, and
+a typed `#inner` reader returns the declared payload type:
+
+```ruby
+class Shape
+  extend Mangrove::Enum
+  variants do
+    variant Circle, Float
+  end
+end
+
+Shape::Circle.new(1.5).inner.floor                # ok — Float
+Shape::Circle.new(1.5).inner.no_such_float_method # error: undefined for Float
+```
+
+## Limitations
+
+- **No generic inference from constructors.** `Result::Ok.new("x")`
+  yields a carrier with no type argument, so unwrap there
+  contributes nothing (a conservative no-op, never a false
+  positive).
+- **Downcast narrowing keeps no type args (ADR-36 Slice B,
+  deferred).** Narrowing a parent generic to a variant via `is_a?`
+  doesn't yet carry the type arguments through the inheritance edge.
+- **Non-constant payload shapes degrade.** A variant whose payload
+  is a shape hash (`{ name: String }`) falls back to `Dynamic[top]`.
+
+## Plugin internals
+
+The carrier-generic instantiation, the `NestedClassTemplate`
+variant synthesis, and the relationship to `rigor-sorbet` are in
+the [plugin's README](../../../plugins/rigor-mangrove/README.md);
+the synthesis tier is [ADR-36](../../adr/36-mangrove-enum-nested-class-emission.md).
+To write a plugin, see [`examples/`](../../../examples/README.md)
+and the [`rigor-plugin-author`](../08-skills.md) skill.

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

@@ -0,0 +1,86 @@
+# rigor-minitest
+
+Narrows local variables through **Minitest** and **Test::Unit**
+assertions — and the Minitest/spec `_(x).must_*` / `.wont_*` matchers
+layered on top. When the plugin recognises a supported assertion shape
+it emits a `:local`-kind narrowing fact, so the rest of the test body
+resolves against the asserted type. It also tells the engine that a
+test framework's `setup` method initialises instance variables, which
+suppresses spurious nil warnings on ivars read in the test body. It
+reads source only, with no `minitest` runtime dependency.
+
+It ships bundled in `rigortype`. Activate it under `plugins:`:
+
+```yaml
+plugins:
+  - rigor-minitest
+```
+
+## What it infers
+
+```ruby
+def test_user
+  user = build_user
+  assert_kind_of(User, user)   # user narrowed to User
+  user.name.upcase             # `.name` resolves on User
+
+  found = find_user(1)
+  refute_nil(found)            # found narrowed away from nil
+  found.id                     # `.id` resolves cleanly
+end
+
+it "narrows the spec way" do
+  _(value).must_be_kind_of(String)   # value narrowed to String
+  value.upcase
+end
+```
+
+`_(x)`, `value(x)`, and `expect(x)` are all accepted as the spec
+wrapper. Test::Unit's `assert_not_kind_of` / `assert_not_nil` /
+`assert_not_equal` / `assert_not_instance_of` share the recogniser with
+their `refute_*` equivalents.
+
+| Assertion / matcher | Effect on `x` |
+| --- | --- |
+| `assert_kind_of(T, x)` / `assert_instance_of(T, x)` | narrow to `T` |
+| `assert_nil(x)` | narrow to `Constant<nil>` |
+| `assert_equal(literal, x)` | narrow to `Constant<literal>` |
+| `assert_match(regex, x)` | narrow to `String` |
+| `refute_kind_of` / `refute_instance_of` (+ `assert_not_*`) | narrow away from `T` |
+| `refute_nil(x)` / `assert_not_nil(x)` | narrow away from nil |
+| `refute_equal(literal, x)` / `assert_not_equal(...)` | narrow away from `Constant<literal>` |
+| `_(x).must_be_kind_of(T)` / `must_be_a(T)` / `must_be_instance_of(T)` / `must_be_an_instance_of(T)` | narrow to `T` |
+| `_(x).must_be_nil` | narrow to `Constant<nil>` |
+| `_(x).must_equal(literal)` | narrow to `Constant<literal>` |
+| `_(x).must_match(regex)` | narrow to `String` |
+| `_(x).wont_be_kind_of(T)` / `wont_be_instance_of(T)` | narrow away from `T` |
+| `_(x).wont_be_nil` | narrow away from nil |
+| `_(x).wont_equal(literal)` | narrow away from `Constant<literal>` |
+
+## No diagnostics, no config
+
+The plugin emits no diagnostics and has no configuration knobs — it
+only contributes narrowing facts to the engine. It walks every analysed
+file; non-test files fall through untouched when no recognised shape
+matches.
+
+## Limitations
+
+- **No block-shape matchers** — `assert_raises(T) { ... }`,
+  `assert_throws(:tag) { ... }`. Narrowing targets straight-line locals.
+- **No predicate / respond-to matchers** — `assert_predicate(x, :foo?)`,
+  `assert_respond_to(x, :m)` need carriers Rigor doesn't model.
+- **No `assert_in_delta` / `assert_operator`** — float-range / generic
+  operator narrowing is future work.
+- **No legacy bare `x.must_be_kind_of(T)`** (Minitest < 6.0) — the
+  receiver *is* the value, so there's nothing to narrow against; migrate
+  to `_(x).must_*`.
+
+## Plugin internals
+
+The assertion recogniser and the contract surfaces this plugin
+exercises — the ADR-37 `type_specifier` narrowing gate and the ADR-38
+`additional_initializers` for `setup` — are in the
+[plugin's README](../../../plugins/rigor-minitest/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-pundit.md

@@ -0,0 +1,72 @@
+# rigor-pundit
+
+Validates Pundit `authorize` / `policy` / `policy_scope` calls
+against a statically-discovered policy index: the policy class must
+exist, and an `authorize(record, :action)` action must correspond
+to a defined `<action>?` predicate on the policy. It reads source
+only — no Pundit runtime dependency.
+
+It ships bundled in `rigortype`. Activate it under `plugins:`:
+
+```yaml
+plugins:
+  - rigor-pundit
+```
+
+## What it checks
+
+```ruby
+# app/policies/post_policy.rb
+class PostPolicy < ApplicationPolicy
+  def show?;    true; end
+  def update?;  true; end
+  def destroy?; true; end
+end
+
+authorize(Post, :show)      # info:  resolves to PostPolicy#show?
+authorize(Post, :destory)   # error: PostPolicy#destory? is not defined (did you mean :destroy?)
+authorize(Comment, :edit)   # error: no policy class CommentPolicy (did you mean … ?)
+```
+
+| Rule | Severity | Fires when |
+| --- | --- | --- |
+| `plugin.pundit.policy-call` | info | an `authorize` / `policy` / `policy_scope` call resolved to a discovered policy |
+| `plugin.pundit.unknown-policy-class` | error | the record maps to a `<Type>Policy` with no entry in the index (with a did-you-mean) |
+| `plugin.pundit.unknown-policy-method` | error | the policy exists but the `:action` has no `<action>?` predicate (lists known predicates + a did-you-mean) |
+| `plugin.pundit.load-error` | warning | policy discovery failed (parse/read error) — once per file |
+
+The record maps to a policy by constant name or inferred
+`Nominal[T]` (`Post` → `PostPolicy`); `:update` normalises to
+`update?`. `authorize(record)` without an action validates only
+the policy class (the action is controller-runtime-bound).
+
+## Configuration
+
+```yaml
+plugins:
+  - gem: rigor-pundit
+    config:
+      policy_search_paths: ["app/policies"]    # default
+      policy_base_classes: ["ApplicationPolicy"]  # default
+```
+
+## Limitations
+
+- **Direct-superclass match only.** `class AdminPostPolicy <
+  AdminPolicy` (where `AdminPolicy < ApplicationPolicy`) isn't
+  discovered unless `AdminPolicy` is added to `policy_base_classes`.
+- **Predicate methods only.** Non-`?` methods, and predicates built
+  with `define_method` or inherited from concerns, are out of
+  scope.
+- **Untyped records pass through.** `authorize(local, :show)` is
+  not validated when `local` has no inferred `Nominal[T]`.
+- **`Scope` policies** are validated for class existence, not for
+  `Scope#resolve`.
+
+## Plugin internals
+
+The policy discoverer / index and the contract surfaces this plugin
+exercises are in the
+[plugin's README](../../../plugins/rigor-pundit/README.md). To
+write a plugin, see [`examples/`](../../../examples/README.md) and
+the [`rigor-plugin-author`](../08-skills.md) skill.