rigortype 0.3.8 → 0.3.9

data/lib/rigor/analysis/runner/diagnostic_aggregator.rb

@@ -22,36 +22,36 @@ module Rigor
       # end-of-pass snapshots) is read through injected reader procs so this collaborator never calls back
       # into the {Runner} and the read happens at the exact point in the run the original inline read did.
       class DiagnosticAggregator # rubocop:disable Metrics/ClassLength
-        # @param configuration [Rigor::Configuration]
-        # @param rbs_extended_reporter [RbsExtended::Reporter]
-        # @param boundary_cross_reporter [DependencySourceInference::BoundaryCrossReporter]
-        # @param source_rbs_synthesis_reporter [Plugin::SourceRbsSynthesisReporter]
-        # @param plugin_registry [#call] reader returning the current {Plugin::Registry} (varies per run).
-        # @param dependency_source_index [#call] reader returning the current
+        # @param plugin_registry — reader returning the current {Plugin::Registry} (varies per run).
+        # @param dependency_source_index — reader returning the current
         #   {DependencySourceInference::Index}.
-        # @param pool_mode [#call] reader returning the pool-mode flag.
-        # @param cached_plugin_prepare_diagnostics [#call] reader returning the prepare-diagnostic snapshot.
-        # @param pre_eval_diagnostics_from_scanner [#call] reader returning the pre-eval scanner diagnostics.
-        # @param synthesized_namespaces_snapshot [#call] reader.
-        # @param quarantined_signatures_snapshot [#call] reader returning the `signature_paths:` files skipped
+        # @param pool_mode — reader returning the pool-mode flag.
+        # @param cached_plugin_prepare_diagnostics — reader returning the prepare-diagnostic snapshot.
+        # @param pre_eval_diagnostics_from_scanner — reader returning the pre-eval scanner diagnostics.
+        # @param synthesized_namespaces_snapshot — reader.
+        # @param quarantined_signatures_snapshot — reader returning the `signature_paths:` files skipped
         #   because they do not parse (`[path, first_error_line]` pairs).
-        # @param env_build_failure_snapshot [#call] reader returning the total RBS env-build failure tuple
+        # @param signature_standdowns_snapshot — reader returning the plugin-contributed signature files
+        #   that stood down against a colliding generic arity (#610), as
+        #   `[path, class_name, existing_arity, incoming_arity, existing_file]` tuples. Defaults to none so
+        #   a caller that snapshots nothing of the kind need not say so.
+        # @param env_build_failure_snapshot — reader returning the total RBS env-build failure tuple
         #   (`[error_class, first_error_line, conflicting_buffer_names]`) or nil when the env built.
-        # @param definition_build_failures_snapshot [#call] issue #696 — reader returning the per-class
+        # @param definition_build_failures_snapshot — issue #696 — reader returning the per-class
         #   `RBS::DefinitionBuilder` failures the run observed, as `[class_name, error_class, member,
         #   conflicting_buffer_names]` tuples. Empty for a healthy sig set.
-        # @param hkt_scan_failure_snapshot [#call] issue #784 — reader returning the `[error_class_name,
+        # @param hkt_scan_failure_snapshot — issue #784 — reader returning the `[error_class_name,
         #   first_message_line, raw_frame_or_nil, stage]` tuple whichever stage of the HKT-registry build
         #   raised, or nil when both built (or were never demanded). `stage` is `:scan` (the RBS `type`-alias
         #   scan) or `:overlay` (the plugin-manifest aggregation, #791), and picks the row's wording.
-        # @param conformance_results_snapshot [#call] reader.
+        # @param conformance_results_snapshot — reader.
         def initialize(configuration:, rbs_extended_reporter:, boundary_cross_reporter:, # rubocop:disable Metrics/ParameterLists
                        source_rbs_synthesis_reporter:, plugin_registry:, dependency_source_index:,
                        pool_mode:, cached_plugin_prepare_diagnostics:,
                        pre_eval_diagnostics_from_scanner:, synthesized_namespaces_snapshot:,
                        quarantined_signatures_snapshot:, env_build_failure_snapshot:,
                        definition_build_failures_snapshot:, hkt_scan_failure_snapshot:,
-                       conformance_results_snapshot:)
+                       conformance_results_snapshot:, signature_standdowns_snapshot: -> { [] })
           @configuration = configuration
           @rbs_extended_reporter = rbs_extended_reporter
           @boundary_cross_reporter = boundary_cross_reporter
@@ -63,6 +63,7 @@ module Rigor
           @pre_eval_diagnostics_from_scanner_reader = pre_eval_diagnostics_from_scanner
           @synthesized_namespaces_snapshot_reader = synthesized_namespaces_snapshot
           @quarantined_signatures_snapshot_reader = quarantined_signatures_snapshot
+          @signature_standdowns_snapshot_reader = signature_standdowns_snapshot
           @env_build_failure_snapshot_reader = env_build_failure_snapshot
           @definition_build_failures_snapshot_reader = definition_build_failures_snapshot
           @hkt_scan_failure_snapshot_reader = hkt_scan_failure_snapshot
@@ -416,6 +417,26 @@ module Rigor
           [build_rbs_synthesized_namespace_diagnostic(synthesized)]
         end
 
+        # Issue #610 — the outcome that AVOIDED `rbs.coverage.definition-build-failed`'s rung: a signature
+        # file a loaded plugin contributes re-declared a class another loaded source (typically an `rbs
+        # collection install`) already declares at a DIFFERENT generic arity, so the plugin's file stood
+        # down rather than fail the class's definition build. One `:info` per file: the user is told what
+        # typing they are not getting and why, and — unlike the quarantine row this file used to be
+        # misreported as — is not sent to remove a declaration the plugin owns.
+        def rbs_plugin_signature_stood_down_diagnostics
+          standdowns = signature_standdowns_snapshot
+          return [] if standdowns.nil? || standdowns.empty?
+
+          standdowns.map { |entry| build_rbs_plugin_signature_stood_down_diagnostic(entry) }
+        end
+
+        # The two `:info` notices that close the `rbs.coverage.*` ladder, in this order: the namespace
+        # synthesis first, then the stand-down (#610) — the outcome that AVOIDED a definition-build failure
+        # and so the quietest row on it. One method so the runner's assembly reads them as one slot.
+        def rbs_coverage_notice_diagnostics
+          rbs_synthesized_namespace_diagnostics + rbs_plugin_signature_stood_down_diagnostics
+        end
+
         # Maps the per-run `rigor:v1:conforms-to` scan results into diagnostics (spec: `rbs-extended.md` §
         # "Explicit conformance directive"). A class that declares `conforms-to _Interface` but is missing
         # a required interface method surfaces as `rbs_extended.unsatisfied-conformance`; an unresolvable
@@ -436,16 +457,28 @@ module Rigor
           when RbsExtended::ConformanceChecker::IncompatibleSignature
             build_incompatible_signature_diagnostic(record)
           else # UnresolvedInterface
-            build_reporter_diagnostic(
-              record.location,
-              rule: "dynamic.rbs-extended.unresolved",
-              message: "`#{record.class_name}` declares `conforms-to #{record.interface_name}` but " \
-                       "interface `#{record.interface_name}` is not loaded. Check for a typo or add " \
-                       "the `sig`/library that declares it to the RBS load path."
-            )
+            build_unresolved_conformance_diagnostic(record)
           end
         end
 
+        # Issue #928 — `:warning`, not the `:info` the other `dynamic.rbs-extended.unresolved` producers
+        # stamp. Those report that an inference fell back; this one reports that an assertion the author
+        # deliberately wrote is checking NOTHING, and the whole point of `conforms-to` is to be checked. It
+        # is not unsolicited either: only a project that wrote the directive can see it. Now that the
+        # capability-role catalog ships, the remaining way to reach this row is a name that does not exist.
+        def build_unresolved_conformance_diagnostic(record)
+          path, line, column = location_fields(record.location)
+          Diagnostic.new(
+            path: path, line: line, column: column,
+            message: "`#{record.class_name}` declares `conforms-to #{record.interface_name}` but " \
+                     "interface `#{record.interface_name}` is not loaded. Check for a typo or add " \
+                     "the `sig`/library that declares it to the RBS load path.",
+            severity: :warning,
+            rule: "dynamic.rbs-extended.unresolved",
+            source_family: :builtin
+          )
+        end
+
         def build_unsatisfied_conformance_diagnostic(record)
           path, line, column = location_fields(record.location)
           Diagnostic.new(
@@ -544,14 +577,27 @@ module Rigor
                      "#{first_failure_clause(failures.first)}#{conflicting_files_clause(files, sample_size)} " \
                      "Rigor still treats each class as KNOWN, so calls into it — real methods and typos " \
                      "alike — silently read `Dynamic[top]` instead of resolving, and this run is quieter " \
-                     "than it should be rather than cleaner. Two signature sources declare the same " \
-                     "member; remove the duplicate declaration (`rbs validate`) to restore type coverage.",
+                     "than it should be rather than cleaner. #{definition_build_advice(failures.first)}",
             severity: :warning,
             rule: "rbs.coverage.definition-build-failed",
             source_family: :builtin
           )
         end
 
+        # The closing advice follows the FIRST failure's error class: `GenericParameterMismatchError` is two
+        # declarations of one CLASS at different generic arity (#610), and "remove the duplicate member"
+        # sends its reader after a member that does not exist.
+        def definition_build_advice(failure)
+          _, error_class, = failure
+          if error_class.to_s.end_with?("GenericParameterMismatchError")
+            "Two signature sources declare the class with a different number of type parameters; make " \
+              "the declarations agree (`rbs validate`) to restore type coverage."
+          else
+            "Two signature sources declare the same member; remove the duplicate declaration " \
+              "(`rbs validate`) to restore type coverage."
+          end
+        end
+
         # `[class_name, error_class, member, buffers]`. The member is nil for the error classes that carry no
         # name at all (`RecursiveAncestorError`), and the clause then names the error class alone rather than
         # inventing a member.
@@ -665,6 +711,42 @@ module Rigor
           )
         end
 
+        def build_rbs_plugin_signature_stood_down_diagnostic(entry)
+          path, class_name, existing_arity, incoming_arity, existing_file = entry
+          displaced_by = displacing_source_phrase(existing_file)
+          Diagnostic.new(
+            path: ".rigor.yml",
+            line: 1,
+            column: 1,
+            message: "`#{relative_signature_path(path.to_s)}` (a signature file a plugin contributes) declares " \
+                     "`#{class_name.to_s.delete_prefix('::')}` with #{type_parameter_phrase(incoming_arity)}, " \
+                     "but #{displaced_by} already declares it with #{type_parameter_phrase(existing_arity)}. " \
+                     "Two declarations of one class at different generic arity fail its definition build, so " \
+                     "the plugin's file stood down: calls into the class resolve against the other " \
+                     "declaration, and the plugin's element typing for it is unavailable while both are " \
+                     "loaded. Expected when a bundled plugin and an `rbs collection install` both declare " \
+                     "the class; nothing to fix unless you want the plugin's typing back, which needs the " \
+                     "other source to stop declaring the class.",
+            severity: :info,
+            rule: "rbs.coverage.plugin-signature-stood-down",
+            source_family: :builtin
+          )
+        end
+
+        def displacing_source_phrase(existing_file)
+          return "another loaded signature source" if existing_file.nil?
+
+          "`#{relative_signature_path(existing_file.to_s)}`"
+        end
+
+        def type_parameter_phrase(arity)
+          case arity
+          when nil, 0 then "no type parameters"
+          when 1 then "1 type parameter"
+          else "#{arity} type parameters"
+          end
+        end
+
         def build_rbs_coverage_missing_diagnostic(missing)
           sample_size = 5
           sample = missing.first(sample_size).map(&:gem_name)
@@ -722,7 +804,22 @@ module Rigor
             )
           end
 
-          unresolved + lossy + hkt_directive_diagnostics
+          unresolved + lossy + hkt_directive_diagnostics + deprecated_form_diagnostics
+        end
+
+        # ADR-109 WD3 — one row per annotation still written in a spelling the grammar accepts but no
+        # longer displays. The row names the replacement because the deprecation window exists for exactly
+        # this edit, and it stays `:info`: the annotation resolved, the run is as green as it was.
+        def deprecated_form_diagnostics
+          @rbs_extended_reporter.deprecated_forms.map do |entry|
+            build_positioned_reporter_diagnostic(
+              entry,
+              rule: "dynamic.rbs-extended.deprecated-form",
+              message: "`#{entry.payload}` is a deprecated spelling; write `#{entry.replacement}`. The " \
+                       "angle-bracket integer range is accepted for one deprecation window and removed " \
+                       "at the next compatibility break (ADR-109)."
+            )
+          end
         end
 
         # Issue #785 — one row per declined HKT directive. The consequence sentence is the point: the parser
@@ -811,6 +908,56 @@ module Rigor
           end
         end
 
+        # Issue #959 — surfaces the {Plugin::IoBoundary} refusal history each loaded plugin accumulated over
+        # the whole run (prepare AND every per-file call: `#io_boundary` is memoised per plugin instance, so
+        # one boundary sees both). `TrustPolicy#allow_read?` stays `File.expand_path`-only per ADR-2 — a
+        # project rooted under a symlink (macOS' `/tmp` → `/private/tmp` is the common case) can have every
+        # plugin read fall outside its own read roots with nothing said about it. One `:info` row per plugin
+        # that hit this, never one per path, naming the count and the first path so the row stays legible on
+        # a plugin that walked a whole out-of-scope subtree.
+        #
+        # Positioned here, in `#pre_file_diagnostics`'s post-analysis sibling list (called from
+        # `Runner#assemble_run_diagnostics`, which only runs on an ADR-45 cache MISS): the refusal history is
+        # a function of the plugin code and the resolved paths for THIS configuration, so it is deterministic
+        # across runs of the same inputs and the row that lands in a miss's cached diagnostics blob is the
+        # row a later warm HIT correctly re-serves — the same regeneration contract every other stream
+        # aggregated in `#pre_file_diagnostics` / `#assemble_run_diagnostics` already relies on (see
+        # `docs/type-specification/diagnostic-policy.md` § "Run-level rows and the record-and-validate
+        # cache"). It is also never routed through `IncrementalSession`'s per-file cache (`#788`): that cache
+        # holds only `Runner#per_file_diagnostics`, and this row is not part of that stream.
+        #
+        # Scope: `plugin_registry` here is the coordinator-side registry, which only actually RUNS `#prepare`
+        # / per-file analysis in sequential mode (`--workers` unset, the default) — a pooled run (`--workers
+        # N`) prepares and analyses on per-worker `WorkerSession` registries this reader never sees, so a
+        # refusal confined to a pooled worker's slice is not reported. Left out deliberately: draining it
+        # needs a fourth marshalled channel beside `drain_reporters` / `drain_dependencies` / `drain_effects`
+        # in `Runner::PoolCoordinator`, and the default (unpooled) path already covers the reported bug.
+        def plugin_trust_refusal_diagnostics
+          return [] if plugin_registry.empty?
+
+          plugin_registry.plugins.filter_map { |plugin| plugin_trust_refusal_diagnostic(plugin) }
+        end
+
+        def plugin_trust_refusal_diagnostic(plugin)
+          summary = plugin.io_boundary.refusal_summary
+          return nil if summary.nil?
+
+          plugin_id = plugin.manifest.id
+          Diagnostic.new(
+            path: ".rigor.yml", line: 1, column: 1,
+            message: "plugin #{plugin_id.inspect} had #{summary[:count]} read(s) refused by the trust " \
+                     "policy; first refused path: #{summary[:first_path].inspect}, outside read root " \
+                     "#{summary[:nearest_root].inspect}. Spell the path the way that read root spells it " \
+                     "(a symlink alias such as macOS' /tmp does not match its real path), or add a " \
+                     "`plugins_io.allowed_paths:` entry in .rigor.yml covering the path.",
+            severity: :info,
+            rule: "plugin_trust.read-refused",
+            source_family: :builtin
+          )
+        rescue StandardError
+          nil
+        end
+
         def build_reporter_diagnostic(source_location, rule:, message:)
           path, line, column = location_fields(source_location)
           Diagnostic.new(
@@ -889,6 +1036,10 @@ module Rigor
           @quarantined_signatures_snapshot_reader.call
         end
 
+        def signature_standdowns_snapshot
+          @signature_standdowns_snapshot_reader.call
+        end
+
         def env_build_failure_snapshot
           @env_build_failure_snapshot_reader.call
         end

data/lib/rigor/analysis/runner/effect_annotation_residual_pass.rb

@@ -58,8 +58,7 @@ module Rigor
                   "every run of the project."
         private_constant :MESSAGE
 
-        # @param configuration [Rigor::Configuration]
-        # @param virtual_rbs [Array<Array(String, String)>, nil] `[buffer name, RBS source]` pairs the
+        # @param virtual_rbs — `[buffer name, RBS source]` pairs the
         #   run ALREADY resolved; never a loader built for this pass. Empty / nil simply drops the
         #   virtual-RBS stratum.
         def initialize(configuration:, virtual_rbs: nil)
@@ -67,7 +66,7 @@ module Rigor
           @virtual_rbs = virtual_rbs
         end
 
-        # @return [Array<Diagnostic>] zero or one.
+        # @return zero or one.
         def diagnostics
           return NO_DIAGNOSTICS if @configuration.effects_enabled?
           return NO_DIAGNOSTICS if @configuration.disabled_rules.include?(RULE)

data/lib/rigor/analysis/runner/effect_envelope_pass.rb

@@ -78,22 +78,21 @@ module Rigor
         LABELS_CONSEQUENCE = "the label is not registered"
         private_constant :LABELS_CONSEQUENCE
 
-        # @param configuration [Rigor::Configuration]
-        # @param rbs_loader [Rigor::Environment::RbsLoader, nil] the run's loader; nil disables the pass.
-        # @param effect_table [Rigor::Effects::EffectTable] the propagated graph.
-        # @param discovery [#call] forces and returns the cross-file discovery tables as
+        # @param rbs_loader — the run's loader; nil disables the pass.
+        # @param effect_table — the propagated graph.
+        # @param discovery — forces and returns the cross-file discovery tables as
         #   `[def_sources, singleton_def_sources, class_sources]`. Called only when a finding needs a
         #   position — a judged-clean envelope never forces it.
-        # @param sources [Hash{String => String}] in-memory sources, for the buffer-backed run path.
-        # @param unit_sources [Hash{String => Array<String>}] `Runner#effect_sources` — where each effect
+        # @param sources — in-memory sources, for the buffer-backed run path.
+        # @param unit_sources — `Runner#effect_sources` — where each effect
         #   unit is defined, which is what an `effects.envelopes[].match:` path glob selects on. Its paths
         #   are relativised against the working directory, which is the project root for every run that
         #   reaches here (the same assumption `Snapshot.build` makes about `reach:`).
-        # @param ancestry [#call, nil] returns the run's as-written superclass table
+        # @param ancestry — returns the run's as-written superclass table
         #   (`FileCollection#superclasses`) — the nominal relation `effect.liskov-widened` reads. A
         #   lambda, and called only once an envelope exists, because merging the run's collections is
-        #   not free.
-        # @param apply_tolerated [Boolean] false runs the judgment with an empty tolerated set
+        #   not free. nil leaves that relation empty.
+        # @param apply_tolerated — false runs the judgment with an empty tolerated set
         #   (`--no-tolerated-effects`).
         def initialize(configuration:, rbs_loader:, effect_table:, discovery:, # rubocop:disable Metrics/ParameterLists
                        sources: nil, unit_sources: nil, ancestry: nil, apply_tolerated: true,
@@ -109,7 +108,7 @@ module Rigor
           @apply_tolerated = apply_tolerated
         end
 
-        # @return [Array<Diagnostic>] one per (method, exceeding label) plus one per unrecognised
+        # @return one per (method, exceeding label) plus one per unrecognised
         #   label, suppression already applied.
         def diagnostics
           return NO_DIAGNOSTICS unless @configuration.effects_check?