rigortype 0.1.18 → 0.1.19

data/skills/rigor-plugin-author/references/02-walker-and-types.md

@@ -37,12 +37,15 @@ rows the rule positions with `diagnostic` (the bundled plugins follow
 this `Analyzer.violations_for` split, which also makes the logic
 unit-testable without running the whole engine).
 
-> The legacy `diagnostics_for_file(path:, scope:, root:)` hook — where
-> you hand-rolled a `def walk` / `compact_child_nodes.each` recursion
-> over `root` yourself — is the **deprecated whole-file escape valve**.
-> Use it only for a genuinely file-scoped result (a single load-error
-> row, or a check that needs the whole parsed file at once). New
-> node-scoped checks use `node_rule`.
+> `diagnostics_for_file(path:, scope:, root:)` is the **file-rule**
+> surface — use it for a genuinely file-scoped result (a single
+> load-error row, a cross-file aggregation, or a check that needs the
+> whole parsed file at once). It is not deprecated; it is the right tool
+> when a check isn't per-node. Per-node checks use `node_rule` (you don't
+> hand-roll a `def walk` / `compact_child_nodes.each` recursion — the
+> engine owns the walk). Map a violation array to diagnostics with
+> `diagnostics_for(violations, path:, node:)` rather than a hand-rolled
+> `.map { diagnostic(...) }`.
 
 ### Recognising call sites
 
@@ -59,7 +62,9 @@ re-deriving the `unescaped.to_sym` shape.
   validate references): declare `node_file_context { |root, scope| … }`.
   It runs once per file before the walk and its return value is threaded
   to every rule as `file_context`. (A *cross-file* collect belongs in
-  `#prepare` + `services.fact_store` instead — see
+  `#prepare` + `services.fact_store.publish`; the consuming plugin reads
+  it with `read_fact(plugin_id:, name:)` — the nil-inclusive memo means
+  you never hand-roll an `@x_resolved` flag. See
   [`01-plan-and-scaffold.md`](01-plan-and-scaffold.md).)
 - **Where the node sits**: `context` (a `Rigor::Plugin::NodeContext`)
   carries the lexical ancestor chain — `context.enclosing_def`,
@@ -213,16 +218,16 @@ plugin is confident; a wrong contribution propagates downstream.
 `rigor plugins --capabilities` catalogue enumerates — run it to see
 exactly what each loaded plugin contributes.
 
-> **The deprecated escape valve.** The original fat hook,
-> `flow_contribution_for(call_node:, scope:)`, returns a single
-> `Rigor::FlowContribution` and is still consulted alongside the narrow
-> DSLs. It is retained only for the two shapes the narrow DSLs do not
-> express: a **method-gated return type** (an RSpec `let(:x) { … }`
-> binding, a Sorbet `sig`-driven return — keyed on the method, not a
-> fixed receiver class) and a **dynamic per-project receiver set**
-> (ActiveStorage's `Attached::One` on discovered model classes). If your
-> plugin needs one of those, use `flow_contribution_for`; otherwise
-> prefer `dynamic_return` / `type_specifier`. These return-type surfaces
+> **The removed fat hook.** The original `flow_contribution_for(call_node:,
+> scope:)` was **deleted pre-1.0 in ADR-52 WD3** — defining it now raises
+> `ArgumentError` at load time. The two shapes it used to cover are
+> expressed by `dynamic_return`'s callable gates: a **method-gated return
+> type** (an RSpec `let(:x) { … }` binding, a Sorbet `sig`-driven return —
+> keyed on the method, not a fixed receiver class) uses
+> `dynamic_return methods: -> { [...] }` or `file_methods: ->(path) { [...] }`;
+> a **dynamic per-project receiver set** (ActiveStorage's `Attached::One`
+> on discovered model classes) uses `dynamic_return receivers: -> { [...] }`,
+> the callable resolved once after `#prepare`. These return-type surfaces
 > are the most contract-sensitive part of the API — implement one only
 > if the plugin genuinely needs to sharpen call-site types; a
 > diagnostics-only plugin skips them entirely.

data/skills/rigor-project-init/references/03-baseline-and-bugs.md

@@ -23,6 +23,8 @@ The JSON shape:
 {
   "summary":      { "total": 489, "error": 480, "warning": 9, "info": 0 },
   "distribution": [ { "rule": "call.undefined-method", "count": 437 } ],
+  "selectors":    [ { "receiver": "String", "method": "squish", "count": 31,
+                      "files": 12, "rules": { "call.undefined-method": 31 } } ],
   "hotspots":     [ { "file": "app/models/status.rb", "count": 42,
                       "by_rule": { "call.undefined-method": 40 } } ],
   "hints": [
@@ -32,11 +34,26 @@ The JSON shape:
 }
 ```
 
-Use the three sections like this:
+Use the sections like this:
 
 - **`summary` / `distribution`** — the scale, and which rules
   dominate. Decides nothing on its own; feeds the mode sanity-check
   (>100 errors → acknowledge mode is the right default).
+- **`selectors`** — the by-(class, method) axis. Each row is a
+  dispatch target (`String#squish`) with its `count`, the `files` it
+  spans, and the `rules` that fired. Read it with `jq` to find the
+  *shape* of the problem before touching code — these are structured
+  fields, never parse the `message`:
+  ```sh
+  # the 10 methods responsible for the most diagnostics
+  rigor triage --format json | jq -r '.selectors[:10][] | "\(.count)\t\(.receiver)#\(.method)"'
+  # methods missing on the same receiver across many files = one config
+  # gap (an unloaded core-ext / unseen monkey-patch), not many bugs
+  rigor triage --format json | jq '.selectors[] | select(.files >= 5)'
+  ```
+  A high `count` + high `files` selector is almost always a *systemic
+  cause* (a plugin / `pre_eval:` fix clears it in bulk); a low `count`
+  selector is a candidate genuine bug.
 - **`hotspots`** — files carrying the most diagnostics. A single hot
   file is often one structural cause, not many bugs.
 - **`hints`** — the heuristic catalogue. Each hint names a *likely

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rigortype
 version: !ruby/object:Gem::Version
-  version: 0.1.18
+  version: 0.1.19
 platform: ruby
 authors:
 - Rigor contributors
@@ -289,6 +289,7 @@ files:
 - lib/rigor/analysis/check_rules/always_truthy_condition_collector.rb
 - lib/rigor/analysis/check_rules/dead_assignment_collector.rb
 - lib/rigor/analysis/check_rules/ivar_write_collector.rb
+- lib/rigor/analysis/check_rules/main_pass_collector.rb
 - lib/rigor/analysis/check_rules/rule_walk.rb
 - lib/rigor/analysis/check_rules/self_closedness_scanner.rb
 - lib/rigor/analysis/check_rules/unreachable_clause_collector.rb
@@ -318,6 +319,7 @@ files:
 - lib/rigor/analysis/worker_session.rb
 - lib/rigor/ast.rb
 - lib/rigor/ast/type_node.rb
+- lib/rigor/bleeding_edge.rb
 - lib/rigor/builtins/hkt_builtins.rb
 - lib/rigor/builtins/imported_refinements.rb
 - lib/rigor/builtins/regex_refinement.rb
@@ -353,6 +355,7 @@ files:
 - lib/rigor/cli/plugins_renderer.rb
 - lib/rigor/cli/prism_colorizer.rb
 - lib/rigor/cli/renderable.rb
+- lib/rigor/cli/show_bleedingedge_command.rb
 - lib/rigor/cli/sig_gen_command.rb
 - lib/rigor/cli/skill_command.rb
 - lib/rigor/cli/trace_command.rb
@@ -386,6 +389,7 @@ files:
 - lib/rigor/flow_contribution/merger.rb
 - lib/rigor/inference/acceptance.rb
 - lib/rigor/inference/block_parameter_binder.rb
+- lib/rigor/inference/body_fixpoint.rb
 - lib/rigor/inference/budget_trace.rb
 - lib/rigor/inference/builtins/array_catalog.rb
 - lib/rigor/inference/builtins/comparable_catalog.rb
@@ -421,6 +425,7 @@ files:
 - lib/rigor/inference/indexed_narrowing.rb
 - lib/rigor/inference/macro_block_self_type.rb
 - lib/rigor/inference/method_dispatcher.rb
+- lib/rigor/inference/method_dispatcher/array_to_h_folding.rb
 - lib/rigor/inference/method_dispatcher/block_folding.rb
 - lib/rigor/inference/method_dispatcher/call_context.rb
 - lib/rigor/inference/method_dispatcher/cgi_folding.rb
@@ -435,6 +440,7 @@ files:
 - lib/rigor/inference/method_dispatcher/overload_selector.rb
 - lib/rigor/inference/method_dispatcher/rbs_dispatch.rb
 - lib/rigor/inference/method_dispatcher/receiver_affinity.rb
+- lib/rigor/inference/method_dispatcher/reduce_folding.rb
 - lib/rigor/inference/method_dispatcher/regexp_folding.rb
 - lib/rigor/inference/method_dispatcher/set_folding.rb
 - lib/rigor/inference/method_dispatcher/shape_dispatch.rb
@@ -489,7 +495,6 @@ files:
 - lib/rigor/plugin/loader.rb
 - lib/rigor/plugin/macro.rb
 - lib/rigor/plugin/macro/block_as_method.rb
-- lib/rigor/plugin/macro/external_file.rb
 - lib/rigor/plugin/macro/heredoc_template.rb
 - lib/rigor/plugin/macro/nested_class_template.rb
 - lib/rigor/plugin/macro/trait_registry.rb

data/lib/rigor/plugin/macro/external_file.rb

@@ -1,143 +0,0 @@
-# frozen_string_literal: true
-
-module Rigor
-  module Plugin
-    module Macro
-      # ADR-16 Tier D declaration: "files matching `glob` are
-      # analysed as if their body were pasted at a call site whose
-      # `self` is an instance of `receiver_type` (and whose `@ivar`
-      # facts come from `bound_ivars`)."
-      #
-      # Worked motivating cases (per the per-library survey):
-      #
-      # - Redmine's `WebhookPayload#instance_eval(File.read(path), path, 1)`
-      #   at `app/models/webhook_payload.rb:71`. The payload templates
-      #   under `config/webhooks/*.rb` run with `self` typed as
-      #   `Redmine::WebhookPayload` and ivars like `@event` / `@issue`
-      #   / `@user` pre-bound by the caller.
-      # - tDiary Core's plugin loader pattern — `misc/plugin/*.rb`
-      #   files loaded under `instance_eval` with the tDiary plugin
-      #   instance as `self`.
-      #
-      # ## Authoring shape
-      #
-      #     manifest(
-      #       id: "redmine-webhook-payloads",
-      #       version: "0.1.0",
-      #       external_files: [
-      #         Rigor::Plugin::Macro::ExternalFile.new(
-      #           glob: "config/webhooks/*.rb",
-      #           receiver_type: "Redmine::WebhookPayload",
-      #           bound_ivars: {
-      #             "@event" => "Symbol",
-      #             "@issue" => "Issue?",
-      #             "@user"  => "User"
-      #           }
-      #         )
-      #       ]
-      #     )
-      #
-      # ## Fields
-      #
-      # - `glob` — non-empty String pattern. Interpreted relative
-      #   to the project root (the directory containing `.rigor.yml`)
-      #   at scan time. Slice 5a accepts any non-empty glob
-      #   pattern syntactically; the engine integration (slice 5b)
-      #   pins the resolution rule.
-      # - `receiver_type` — non-empty String. The class name `self`
-      #   inside the loaded file binds to. Engine integration (slice
-      #   5b) narrows the file-entry scope's `self_type` to
-      #   `Nominal[receiver_type]`.
-      # - `bound_ivars` — Hash<String, String>. Each key MUST start
-      #   with `@`; each value is a non-empty type-name String. The
-      #   engine pre-binds these as ivar facts in the file-entry
-      #   scope (slice 5b).
-      #
-      # ## Slice 5a scope
-      #
-      # **This file ships the value class + manifest hook ONLY.**
-      # The engine integration that (a) adds matched files to the
-      # analysis set, (b) narrows the file-entry `self_type`, and
-      # (c) pre-binds `bound_ivars` as ivar facts is **queued for
-      # slice 5b**, gated on demonstrated demand. The survey
-      # identifies only Redmine + tDiary as concrete consumers;
-      # premature engine work is deferred until those cases (or
-      # equivalents) materialise as committed plugin targets.
-      #
-      # With only this slice landed, plugin authors CAN declare a
-      # Tier D manifest entry today — the declaration round-trips
-      # through `Manifest#to_h` (cache-key stable) and is exposed
-      # on `Manifest#external_files` — but the substrate does not
-      # yet act on it. The contract is forward-compatible: when
-      # slice 5b lands, the engine reads the same declarations and
-      # plugin gems do not need to change.
-      class ExternalFile
-        attr_reader :glob, :receiver_type, :bound_ivars
-
-        def initialize(glob:, receiver_type:, bound_ivars: {})
-          validate_glob!(glob)
-          validate_receiver_type!(receiver_type)
-          validate_bound_ivars!(bound_ivars)
-
-          @glob = glob.dup.freeze
-          @receiver_type = receiver_type.dup.freeze
-          @bound_ivars = bound_ivars.to_h { |k, v| [k.dup.freeze, v.dup.freeze] }.freeze
-          freeze
-        end
-
-        def to_h
-          {
-            "glob" => glob,
-            "receiver_type" => receiver_type,
-            "bound_ivars" => bound_ivars
-          }
-        end
-
-        def ==(other)
-          other.is_a?(ExternalFile) && to_h == other.to_h
-        end
-        alias eql? ==
-
-        def hash
-          to_h.hash
-        end
-
-        private
-
-        def validate_glob!(value)
-          return if value.is_a?(String) && !value.empty?
-
-          raise ArgumentError,
-                "Plugin::Macro::ExternalFile#glob must be a non-empty String, got #{value.inspect}"
-        end
-
-        def validate_receiver_type!(value)
-          return if value.is_a?(String) && !value.empty?
-
-          raise ArgumentError,
-                "Plugin::Macro::ExternalFile#receiver_type must be a non-empty String, got #{value.inspect}"
-        end
-
-        def validate_bound_ivars!(value)
-          unless value.is_a?(Hash)
-            raise ArgumentError,
-                  "Plugin::Macro::ExternalFile#bound_ivars must be a Hash, got #{value.inspect}"
-          end
-
-          value.each do |k, v|
-            unless k.is_a?(String) && k.start_with?("@") && k.length > 1
-              raise ArgumentError,
-                    "Plugin::Macro::ExternalFile#bound_ivars key must be a String starting with `@`, " \
-                    "got #{k.inspect}"
-            end
-            next if v.is_a?(String) && !v.empty?
-
-            raise ArgumentError,
-                  "Plugin::Macro::ExternalFile#bound_ivars value must be a non-empty String, " \
-                  "got #{v.inspect}"
-          end
-        end
-      end
-    end
-  end
-end