rigortype 0.3.2 → 0.3.4

data/plugins/rigor-sidekiq/lib/rigor/plugin/sidekiq/schedule_scan.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Rigor
+  module Plugin
+    class Sidekiq < Rigor::Plugin::Base
+      # ADR-102 WD3 / #367 — which workers does this project enqueue by NAME, from schedule configuration?
+      #
+      # This is the one genuinely Sidekiq-specific reachability root, and the reason it is worth reading YAML
+      # for: a cron-scheduled worker is enqueued from `config/schedule.yml` as the string `"HardWorker"`, so
+      # the repository may contain no `HardWorker.perform_async` anywhere. The constant scan sees nothing, and
+      # `rigor unused` reports a worker that runs every night as dead code.
+      #
+      # Two layouts, one key. `sidekiq-cron` writes the schedule as the whole document
+      # (`{ name => { "cron" =>, "class" => } }`); `sidekiq-scheduler` nests the same entries under
+      # `config/sidekiq.yml`'s `:scheduler: :schedule:` block. Both name the worker under `class:`, and
+      # `class:` is the ONLY key read here.
+      #
+      # **What this refuses to read is the queue list.** `:queues:` in `sidekiq.yml` holds queue names, and a
+      # queue name is not a class name — inflecting `report_worker` into `ReportWorker` would manufacture a
+      # root out of a naming coincidence, which is precisely the over-supply this plugin declined in #350. An
+      # over-claiming root source silently hides real dead code (ADR-102 § Consequences), and nothing
+      # downstream can tell you it happened. So a queue contributes nothing, deliberately.
+      #
+      # Names are not trusted either: the caller intersects them with the workers {WorkerDiscoverer} actually
+      # found, so a typo or an out-of-tree class costs coverage rather than manufacturing a root, and the
+      # report's `matched no declaration` counter stays meaningful.
+      #
+      # Fail-soft throughout, because this reads user-authored config that Rigor does not own: an absent file,
+      # an unreadable one, a YAML syntax error, or a document that is not a Hash contributes nothing rather
+      # than raising. `rigor unused` is a report a human reads, and refusing to print it because one
+      # `sidekiq.yml` has a stray tab is a bad trade.
+      class ScheduleScan
+        # The key naming the worker, in both layouts. Symbol keys are accepted because `sidekiq.yml` is
+        # conventionally written with them (`:scheduler:`, `:schedule:`), and Psych parses `:class:` as the
+        # Symbol `:class`.
+        CLASS_KEY = "class"
+
+        # Where a schedule block hides inside a document. `[]` is the document itself — `sidekiq-cron`'s
+        # `schedule.yml` IS the schedule map — and the nested paths are `sidekiq-scheduler`'s, whose entries
+        # live under `:scheduler: :schedule:` (with the bare `:schedule:` form kept for pre-3.0 layouts).
+        SCHEDULE_BLOCK_KEY_PATHS = [[], %w[scheduler schedule], %w[schedule]].freeze
+
+        # Errno classes that mean "this path is not readable as a schedule" — swallowed so one bad path does
+        # not cost the roots the other paths supply.
+        IO_ERRORS = [Errno::ENOENT, Errno::EACCES, Errno::EISDIR].freeze
+
+        def initialize(io_boundary:, schedule_paths:)
+          @io_boundary = io_boundary
+          @schedule_paths = schedule_paths
+        end
+
+        # @return [Array<String>] the class names named by a `class:` key in a schedule entry, sorted and
+        #   unique. NOT yet intersected with the discovered workers — the caller does that.
+        def worker_names
+          names = Set.new
+          @schedule_paths.each do |path|
+            document = load_document(path)
+            next unless document.is_a?(Hash)
+
+            SCHEDULE_BLOCK_KEY_PATHS.each { |keys| collect_entries(dig_block(document, keys), names) }
+          end
+          names.to_a.sort
+        end
+
+        private
+
+        def load_document(path)
+          absolute = File.expand_path(path.to_s)
+          return nil unless File.file?(absolute)
+
+          contents = read_safely(absolute)
+          contents && parse_safely(contents)
+        end
+
+        def read_safely(path)
+          @io_boundary.read_file(path)
+        rescue Plugin::AccessDeniedError, *IO_ERRORS
+          nil
+        end
+
+        # `safe_load` with no permitted classes beyond Symbol: a schedule file is data, and Rigor never loads
+        # the Rails environment or the sidekiq runtime to read it. `aliases: true` because YAML anchors are
+        # ordinary style in a hand-maintained schedule.
+        def parse_safely(contents)
+          YAML.safe_load(contents, aliases: true, permitted_classes: [Symbol])
+        rescue Psych::Exception
+          nil
+        end
+
+        # Walks one of {SCHEDULE_BLOCK_KEY_PATHS} into the document. String and Symbol keys are both tried because
+        # `sidekiq.yml` is written with Symbol keys and `schedule.yml` with String ones.
+        def dig_block(document, keys)
+          keys.reduce(document) do |node, key|
+            return nil unless node.is_a?(Hash)
+
+            fetch_either(node, key)
+          end
+        end
+
+        # A schedule block maps an arbitrary job NAME to an entry Hash. Only the entry's own `class:` is read
+        # — no recursion into the value, so a nested option that happens to be called `class` cannot enter,
+        # and neither can anything under `:queues:`, whose values are Strings and Arrays rather than entries.
+        def collect_entries(block, names)
+          return unless block.is_a?(Hash)
+
+          block.each_value do |entry|
+            next unless entry.is_a?(Hash)
+
+            value = fetch_either(entry, CLASS_KEY)
+            names << value if value.is_a?(String) && !value.empty?
+          end
+        end
+
+        def fetch_either(hash, key)
+          hash.fetch(key) { hash[key.to_sym] }
+        end
+      end
+    end
+  end
+end

data/plugins/rigor-sidekiq/lib/rigor/plugin/sidekiq.rb

@@ -4,6 +4,7 @@ require "rigor/plugin"
 
 require_relative "sidekiq/worker_index"
 require_relative "sidekiq/worker_discoverer"
+require_relative "sidekiq/schedule_scan"
 require_relative "sidekiq/analyzer"
 
 module Rigor
@@ -22,6 +23,7 @@ module Rigor
     #         config:
     #           worker_search_paths: ["app/workers", "app/sidekiq"]   # default; optional
     #           worker_marker_modules: ["Sidekiq::Job", "Sidekiq::Worker"]  # default; optional
+    #           schedule_paths: ["config/schedule.yml", "config/sidekiq.yml"]  # default; optional
     #
     # ## What it checks
     #
@@ -30,6 +32,11 @@ module Rigor
     #    schedule and forward the rest. Mismatches emit `wrong-arity`.
     # 2. **Missing schedule** — `perform_in()` / `perform_at()` with zero arguments emit `missing-schedule`.
     #
+    # ## What it contributes to `rigor unused`
+    #
+    # The workers a schedule file names under `class:` and nothing else (ADR-102 WD3 / #367) — see
+    # {#prepare} and {ScheduleScan}.
+    #
     # ## Limitations (v0.1.0)
     #
     # - Direct `include` matches only against the configured marker modules. Indirect includes via a
@@ -41,12 +48,21 @@ module Rigor
     class Sidekiq < Rigor::Plugin::Base
       manifest(
         id: "sidekiq",
-        version: "0.1.0",
+        # Bumped 2026-08-16 — publishes `:reachability_roots` for `rigor unused` (ADR-102 WD3): the workers
+        # a schedule file enqueues by name, which no `perform_async` call site writes down.
+        version: "0.2.0",
         description: "Validates Sidekiq `Worker.perform_async` argument arity.",
         config_schema: {
           "worker_search_paths" => { kind: :array, default: ["app/workers", "app/sidekiq"] },
-          "worker_marker_modules" => { kind: :array, default: %w[Sidekiq::Job Sidekiq::Worker] }
-        }
+          "worker_marker_modules" => { kind: :array, default: %w[Sidekiq::Job Sidekiq::Worker] },
+          # `schedule_paths` — the schedule configuration {ScheduleScan} reads for the reachability roots
+          # below. The two defaults are the conventional locations of the two schedule layouts in the wild:
+          # `sidekiq-cron`'s `config/schedule.yml` and `sidekiq-scheduler`'s `:scheduler: :schedule:` block
+          # inside `config/sidekiq.yml`. A project that keeps its schedule elsewhere lists the file itself;
+          # these are file paths, not directories, because a schedule is a named document rather than a tree.
+          "schedule_paths" => { kind: :array, default: ["config/schedule.yml", "config/sidekiq.yml"] }
+        },
+        produces: [:reachability_roots]
       )
 
       producer :worker_index, watch: -> { [[@worker_search_paths, "**/*.rb"]] } do |_params|
@@ -57,9 +73,46 @@ module Rigor
         ).discover
       end
 
+      # Cached separately from `:worker_index` because the two invalidate on different files: editing a
+      # schedule changes which workers are reached without touching `app/workers` at all. The `watch:` roots
+      # the glob at the working directory so that CREATING a schedule file — not just editing one — is seen.
+      producer :scheduled_workers, watch: -> { [[".", *@schedule_paths]] } do |_params|
+        ScheduleScan.new(
+          io_boundary: io_boundary,
+          schedule_paths: @schedule_paths
+        ).worker_names
+      end
+
       def init(_services)
         @worker_search_paths = Array(config.fetch("worker_search_paths")).map(&:to_s)
         @worker_marker_modules = Array(config.fetch("worker_marker_modules")).map(&:to_s)
+        @schedule_paths = Array(config.fetch("schedule_paths")).map(&:to_s)
+      end
+
+      # ADR-102 WD3 — publishes the workers a schedule file enqueues BY NAME, for `rigor unused`.
+      #
+      # `MyWorker.perform_async(...)` writes the worker's name as an ordinary constant, so the report's scan
+      # already records that edge and a root would add nothing. A worker named only as the string
+      # `class: "MyWorker"` in `config/schedule.yml` is the opposite case: it runs every night and the
+      # constant appears nowhere, so it reads as dead.
+      #
+      # The intersection is what keeps the contribution honest, exactly as in `rigor-pundit`. {ScheduleScan}
+      # says which names the schedule WRITES; {WorkerDiscoverer} says which workers EXIST. A `class:` value
+      # matching no discovered worker — a typo, a renamed class, a job living outside `worker_search_paths` —
+      # is dropped rather than published, so the failure mode is a missing root (a candidate row a human can
+      # judge) instead of a spurious one (silence where dead code used to be).
+      #
+      # Publishing the discovered worker set instead would have been one line and is what this refuses to do:
+      # "a file exists under `app/workers`" is not evidence that anything enqueues it.
+      def prepare(services)
+        index = producer_value(:worker_index)
+        scheduled = producer_value(:scheduled_workers)
+        return if index.nil? || scheduled.nil?
+
+        roots = scheduled.select { |name| index.known?(name) }
+        return if roots.empty?
+
+        services.fact_store.publish(plugin_id: manifest.id, name: :reachability_roots, value: roots)
       end
 
       # File-level only: the load-error emission. The per-call arity validation runs over the engine-owned

data/sig/rigor/analysis/fact_store.rbs

@@ -5,6 +5,7 @@ module Rigor
       def self?.build_node_collectors: (String path, untyped scope_index) -> Hash[Symbol, untyped]
       def self?.node_collector_driver: (Hash[Symbol, untyped] collectors) -> untyped
       def self?.shadow_verify_converged_collectors: (String path, untyped root, untyped scope_index, Hash[Symbol, untyped]? collectors) -> void
+      def self?.filter_suppressed: (Array[Diagnostic] diagnostics, comments: untyped, disabled_rules: Array[String]) -> Array[Diagnostic]
     end
 
     class FactStore

data/sig/rigor/inference.rbs

@@ -163,6 +163,8 @@ module Rigor
     module ScopeIndexer
       def self?.index: (untyped root, default_scope: Scope) -> Hash[untyped, Scope]
       def self?.build_declaration_overrides: (untyped root) -> Hash[untyped, Type::t]
+      def self?.build_declaration_artifacts: (untyped root) -> [Hash[untyped, Type::t], Hash[String, Type::t]]
+      def self?.build_in_source_constants: (untyped root, Scope default_scope) -> Hash[String, Type::t]
       def self?.record_declarations: (untyped node, Array[String] qualified_prefix, Hash[untyped, Type::t] identity_table, Hash[String, Type::t] discovered) -> void
       def self?.discovered_classes_for_paths: (Array[String] paths, ?buffer: untyped) -> Hash[String, Type::t]
       def self?.discovered_def_index_for_paths: (Array[String] paths, ?buffer: untyped) -> Hash[Symbol, untyped]

data/sig/rigor/rbs_extended.rbs

@@ -47,6 +47,12 @@ module Rigor
 
     def self?.parse_conforms_to_annotation: (String? string) -> String?
 
+    # ADR-103 #383 — the effect-envelope reader. `annotations` is any list of RBS annotation nodes
+    # (`RBS::Definition::Method#annotations`, or a declaration / member's own `#annotations`); the result
+    # is a `Rigor::Effects::Envelope`, or nil when the list carries neither purity spelling.
+    def self?.pure_annotation?: (String? string) -> bool
+    def self?.read_effect_envelope: (untyped annotations, owner_key: String, ?source: Symbol, ?registry: untyped, ?reporter: untyped) -> untyped?
+
     class ParamOverride
       attr_reader param_name: Symbol
       attr_reader type: Type::t

data/sig/rigor/scope.rbs

@@ -19,6 +19,7 @@ module Rigor
     attr_reader method_chain_narrowings: Hash[ChainKey, Type::t]
     attr_reader source_path: String?
     attr_reader struct_fold_safe_locals: Set[Symbol]
+    attr_reader opaque_block_self: bool
 
     # ADR-53 Track A — the seed-time discovery tables live on the
     # DiscoveryIndex; Scope keeps per-table readers as delegates.
@@ -90,6 +91,8 @@ module Rigor
     def with_source_path: (String? path) -> Scope
     def with_struct_fold_safe: (Set[Symbol] locals) -> Scope
     def struct_fold_safe?: (String | Symbol name) -> bool
+    def entering_opaque_block: () -> Scope
+    def opaque_block_self?: () -> bool
     def with_discovery: (DiscoveryIndex index) -> Scope
     def local: (String | Symbol name) -> Type::t?
     def ivar: (String | Symbol name) -> Type::t?
@@ -123,6 +126,7 @@ module Rigor
     def singleton_def_for: (String | Symbol class_name, String | Symbol method_name) -> untyped?
     def user_def_site_for: (String | Symbol class_name, String | Symbol method_name) -> String?
     def top_level_def_for: (String | Symbol method_name) -> untyped?
+    def bindable_top_level_def_for: (String | Symbol method_name) -> untyped?
     def toplevel?: () -> bool
     def discovered_method_visibility: (String | Symbol class_name, String | Symbol method_name) -> Symbol?
     def superclass_of: (String | Symbol class_name) -> String?

data/sig/rigor.rbs

@@ -14,8 +14,12 @@ module Rigor
     def self.load: (?String? path) -> Configuration
     def self.discover: () -> String?
     def self.load_with_includes: (String path, ?visited: Set[String]) -> Hash[String, untyped]
-    def initialize: (?Hash[String, untyped] data) -> void
+    def initialize: (?Hash[String, untyped] data, ?bool effects_key_present) -> void
     def to_h: () -> Hash[String, untyped]
+    # ADR-103 WD13 — the `effects:` block, nil when the key was absent. Presence is the opt-in.
+    attr_reader effects: Hash[String, untyped]?
+    def effects_enabled?: () -> bool
+    def with_effects_enabled: () -> Rigor::Configuration
   end
 
   class CLI
@@ -58,6 +62,10 @@ module Rigor
       # `node` / `location` are Prism values, received as `untyped`).
       def self.from_node: (untyped node, path: String, message: String, ?severity: Symbol, ?rule: String?, ?source_family: String, ?receiver_type: untyped, ?method_name: untyped, ?project_definition_site: untyped) -> Rigor::Analysis::Diagnostic
       def self.from_location: (untyped location, path: String, message: String, ?severity: Symbol, ?rule: String?, ?source_family: String, ?receiver_type: untyped, ?method_name: untyped, ?project_definition_site: untyped) -> Rigor::Analysis::Diagnostic
+      # `from_message_loc` / `from_name_loc` forward `**` to `from_location`, so their keyword surface is
+      # `from_location`'s; only the positional node differs.
+      def self.from_message_loc: (untyped node, path: String, message: String, ?severity: Symbol, ?rule: String?, ?source_family: String, ?receiver_type: untyped, ?method_name: untyped, ?project_definition_site: untyped) -> Rigor::Analysis::Diagnostic
+      def self.from_name_loc: (untyped node, path: String, message: String, ?severity: Symbol, ?rule: String?, ?source_family: String, ?receiver_type: untyped, ?method_name: untyped, ?project_definition_site: untyped) -> Rigor::Analysis::Diagnostic
     end
 
     class Result
@@ -121,6 +129,18 @@ module Rigor
       def analysis_file_set: (?Array[String] paths) -> Array[String]
       def file_dependents: () -> Hash[String, untyped]
       def prepare_project_scan: (?paths: Array[String]) -> untyped
+      # ADR-103 — the propagated effect graph and the merged per-file collections behind it. A report
+      # surface: never a diagnostic, empty when the configuration carries no `effects:` block. Typed
+      # `untyped` for the same reason `cache_store` is — `Rigor::Effects` is not sig-covered yet
+      # (`spec/rigor/public_api_drift_spec.rb`), and a named reference would raise `RBS::UnknownTypeName`.
+      def effect_table: () -> untyped
+      def effect_collection: () -> untyped
+      # #381 — `{ "Class#m" => [path] }`, which the snapshot's `reach:` globs match against. Same
+      # `untyped` reasoning as its two siblings above.
+      def effect_sources: () -> untyped
+      # #387 — the loaded plugins' compiled effect contributions, read by `rigor effects` so the snapshot's
+      # vocabulary is the one the collection window scanned under. Same `untyped` reasoning again.
+      def effect_plugin_facts: () -> untyped
     end
   end
 end

data/skills/rigor-unused-adjudicate/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: rigor-unused-adjudicate
+description: |
+  Find dead code in a Ruby project with `rigor unused` — establish what the report can see on THIS project first, then adjudicate every row before proposing any deletion. Use this whenever someone asks to find or remove dead code, unused classes, unused constants, or "code nobody calls", whenever they ask what a `rigor unused` report means or which rows are safe to delete, and whenever a dead-code cleanup, codebase inventory, or legacy audit comes up — even if they never say "rigor". The report is a review queue and not a defect list; on an adjudicated corpus target only 4 of 57 rows were genuinely dead, so acting on it directly produces mostly wrong deletions. NOT for deleting a specific class you already know is dead, and NOT for `rigor check` diagnostics (those are ordinary type errors).
+license: MPL-2.0
+metadata:
+  version: 0.2.0
+  homepage: https://github.com/rigortype/rigor
+---
+
+# Adjudicating `rigor unused`
+
+`rigor unused` answers *which project classes and modules does no reachable
+code name?* — not *what can I delete*. Closing that gap is the work, and the
+manual chapter has the method:
+
+```sh
+rigor docs 18-removing-dead-code
+```
+
+Read it before adjudicating anything. It carries the false-positive shapes with
+their measured frequencies, the pre-deletion checklist, and how to report the
+result. This skill exists for the part the chapter cannot do for you: **work out
+what the report can and cannot see on this particular project, before you trust
+a single row.**
+
+Do that first, because every check below changes how the output should be read —
+and skipping one is how a live class ends up on a deletion list.
+
+## Establish the ground first
+
+Run the report and answer these against the project in front of you.
+
+**Are framework roots actually supplied?** The summary prints
+`roots: N (M from plugins, …)`. On a framework application `0 from plugins`
+means nothing is naming your controllers, jobs or policies, so most of the
+report is noise. Stop and fix the plugin configuration — `rigor docs
+07-plugins` — rather than adjudicating hundreds of rows.
+
+**Does the project ship signatures?** If `signature_paths:` is configured, also
+run with it emptied and compare:
+
+```sh
+rigor unused                            # normal
+rigor unused --config /tmp/no-sig.yml   # a copy of your config with signature_paths: []
+```
+
+Adjudicate the union. On one application the signature-free run surfaced three
+genuinely dead classes that the default run never showed. Rows that appear only
+without signatures are still worth checking — signatures reference classes, and
+a reference the report counts is not always one a human would.
+
+**What do `paths:` actually cover?** Only Ruby under those paths is analysed.
+Views are the common gap: a helper called from `app/views/**/*.erb` has no Ruby
+caller at all, and will land in the report looking unused. Before believing any
+helper or presenter row, grep the view tree for it.
+
+**Is the git history usable?** The chapter's checklist uses "when did this file
+last change" as evidence. In a shallow clone, or one whose history is all
+dependency bumps, that signal is empty — notice it and say so rather than
+reporting a bot commit as the file's age.
+
+## Then hand off to the chapter
+
+With that established, follow the chapter. Two things worth holding onto as you
+go, because they are what the report's own design is built around:
+
+**Framework conventions and configuration reach code without naming it.** The
+chapter lists the shapes; the ones that recur hardest are a class named as a
+*string* in `config/*.yml` (a recurring-job schedule, a queue definition), a
+convention that derives one name from another (`FooHelper` from
+`FooController`, a decorator from a model, a join model from
+`has_many :speakers_talks`), and a registration DSL called inside the class
+body. None of these appear as a constant anywhere.
+
+**Wrong rows cascade.** A class used only by a wrongly-classified class follows
+it into the report. When a row turns out to be live, re-check what it
+references before treating those rows as independent findings.
+
+## Two habits that keep the answer honest
+
+**A search that finds nothing proves nothing until it has found something.**
+Before concluding a name appears nowhere, run the same search against a name you
+know is used. Silence from a broken command and silence from dead code look
+identical.
+
+**Over-claiming hides dead code; under-claiming does not.** If you cannot settle
+a row, leave it in the report and say you could not settle it. A row left on the
+list is visible to a human; a row you dismissed on a hunch is invisible to
+everyone.