rigortype 0.3.6 → 0.3.8

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

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "../crash_signature"
 require_relative "../diagnostic"
 require_relative "../severity_stamp"
 
@@ -36,12 +37,20 @@ module Rigor
         #   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
         #   (`[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
+        #   `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,
+        #   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.
         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:)
           @configuration = configuration
           @rbs_extended_reporter = rbs_extended_reporter
@@ -55,6 +64,8 @@ module Rigor
           @synthesized_namespaces_snapshot_reader = synthesized_namespaces_snapshot
           @quarantined_signatures_snapshot_reader = quarantined_signatures_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
           @conformance_results_snapshot_reader = conformance_results_snapshot
         end
 
@@ -311,9 +322,11 @@ module Rigor
         # user knows their sig set is malformed (`rbs validate` rejects it) and can fix it at the source.
         # Authored `:info`: the analysis already succeeded; this is advisory, never a gate. Empty for a
         # well-formed sig set.
-        # An unparseable `.rbs` under `signature_paths:` is QUARANTINED so the rest of the env survives
-        # (PR #50), which means the types it declares are silently absent — calls into them read
-        # `Dynamic[top]`, and the run gets *quieter*, not louder. The stderr banner alone never reached CI:
+        # An unparseable or declaration-colliding `.rbs` under `signature_paths:` is QUARANTINED so the
+        # rest of the env survives (PR #50; issue #777 extends this to class-vs-module / constant
+        # collisions against bundled RBS), which means the types it declares are silently absent — calls
+        # into them read `Dynamic[top]`, and the run gets *quieter*, not louder. The stderr banner alone
+        # never reached CI:
         # it is not a diagnostic, so it is absent from `--format json` / SARIF / GitHub annotations / the LSP
         # and cannot move the exit code. This puts it in the diagnostic stream where every channel sees it.
         #
@@ -351,6 +364,51 @@ module Rigor
           [build_rbs_environment_build_failed_diagnostic(failure)]
         end
 
+        # Issue #696 — the third rung of the same ladder, between its two neighbours by consequence: a
+        # QUARANTINED file removes what one FILE declared, this removes what one CLASS declared, an
+        # ENV-BUILD failure removes everything. `RBS::DefinitionBuilder` raising for a class (typically
+        # `DuplicatedMethodDefinitionError`: two signature sources declaring the same method, e.g. a project
+        # `sig/` carrying a vendored COPY of a bundled plugin's `.rbs`) leaves the class KNOWN but with no
+        # method surface, so every call on it — real methods and typos alike — reads `Dynamic[top]`. When
+        # the collision is on a class others inherit, the whole bundled type universe goes with it: the
+        # observed shape is thousands of stderr warnings, ZERO diagnostics, and exit 0.
+        #
+        # Not "drop the class to genuinely-unknown" instead. That also removes diagnostics, so it is not
+        # louder; it changes `Dynamic[top]` semantics for every rule that consults `class_known?`; and
+        # `class_known?` reads {Environment::RbsLoader#known_class_names_set}, a different table from the
+        # definition builder, so it would need a new "known but unbuildable" state regardless. The failure
+        # is made REPORTABLE; the class is not made invisible.
+        #
+        # Authored `:warning`, not `:error`, for the same reason as both neighbours: the collision is
+        # typically between the user's `sig/` and Rigor's OWN bundled RBS, so an `:error` default would let
+        # a Rigor release turn a green build red with no user change (ADR-5 / AGENTS.md § FP discipline).
+        # The `reject-unparseable-signatures` bleeding-edge feature promotes it to `:error`.
+        def rbs_definition_build_failed_diagnostics
+          failures = definition_build_failures_snapshot
+          return [] if failures.nil? || failures.empty?
+
+          [build_rbs_definition_build_failed_diagnostic(failures)]
+        end
+
+        # Issue #784 — the fourth rung, narrowest consequence: one of the two builds behind
+        # `Environment#hkt_registry` raised instead of building. The `:scan` stage is the implicit HKT scan
+        # over RBS `type` aliases (ADR-20 WD2's `%a{rigor:v1:hkt_register / hkt_define}` overlay AND any
+        # recursive `type` alias in the project's own `.rbs` or an installed `rbs collection`); analysis
+        # proceeds over the PRE-scan registry — bundled builtins (`json::value`, …) plus the plugin overlay
+        # — so a `type` alias that would have registered as a type constructor reads its bound
+        # (`Dynamic[top]`) instead. The `:overlay` stage (#791) is the plugin-manifest aggregation, which
+        # sat ABOVE the seam until the run-owned demands made a raise there abort the run; it degrades one
+        # step further in and one step narrower — the plugin entries are dropped, the `.rbs` scan still
+        # runs. Either way everything else this run reports is unaffected: no class loses its method
+        # surface, no signature file is skipped, the environment builds. That is why this sits LAST on the
+        # ladder, after its two `rbs.coverage.*` siblings above.
+        def rbs_hkt_scan_failed_diagnostics
+          failure = hkt_scan_failure_snapshot
+          return [] if failure.nil?
+
+          [build_rbs_hkt_scan_failed_diagnostic(failure)]
+        end
+
         def rbs_synthesized_namespace_diagnostics
           synthesized = synthesized_namespaces_snapshot
           return [] if synthesized.nil? || synthesized.empty?
@@ -428,11 +486,12 @@ module Rigor
             path: ".rigor.yml",
             line: 1,
             column: 1,
-            message: "#{quarantined.size} RBS file(s) under `signature_paths:` do not parse and were " \
-                     "SKIPPED: #{sample.join(', ')}#{suffix}. The rest of your RBS environment still " \
-                     "loaded, but the types those files declare are absent — calls into them read " \
-                     "`Dynamic[top]`, so this run is quieter than it should be, not cleaner. Fix the " \
-                     "parse error(s) (`rbs validate`) to restore that coverage.",
+            message: "#{quarantined.size} RBS file(s) under `signature_paths:` were SKIPPED " \
+                     "(unparseable, or duplicated against bundled RBS): #{sample.join(', ')}#{suffix}. " \
+                     "The rest of your RBS environment still loaded, but the types those files declare " \
+                     "are absent — calls into them read `Dynamic[top]`, so this run is quieter than it " \
+                     "should be, not cleaner. Fix the parse error(s) or remove the conflicting " \
+                     "declaration(s) (`rbs validate`) to restore that coverage.",
             severity: :warning,
             rule: "rbs.coverage.quarantined-signature",
             source_family: :builtin
@@ -462,6 +521,124 @@ module Rigor
           )
         end
 
+        # Issue #696. One diagnostic per RUN, not per class: a collision on a widely-inherited class fails
+        # every descendant, and 2,709 rows saying the same thing about one `.rbs` line is noise, not
+        # visibility.
+        #
+        # The failed-class list alone is not actionable, and that is what the "First failure" clause is for.
+        # A duplicate on `::Object#blank?` fails `String`, `Integer`, `Array` and 1,333 more — every name in
+        # that list is a DESCENDANT, and none of them is where the fix goes. The member comes off the error
+        # object rather than out of its message ({RbsLoader#definition_build_member}), so it names the
+        # culprit and reads the same on a cache hit, where every `RBS::Location` has been dumped to a
+        # sentinel. The error class is attributed to that first failure explicitly rather than to all of
+        # them: the per-class memo keeps only the first reason, and one run can mix error classes.
+        def build_rbs_definition_build_failed_diagnostic(failures)
+          sample_size = 5
+          files = failures.flat_map { |failure| Array(failure[3]) }.uniq.map { |name| relative_signature_path(name) }
+          Diagnostic.new(
+            path: ".rigor.yml",
+            line: 1,
+            column: 1,
+            message: "#{failures.size} RBS class definition(s) failed to build: " \
+                     "#{sampled(failures.map(&:first), sample_size)}." \
+                     "#{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.",
+            severity: :warning,
+            rule: "rbs.coverage.definition-build-failed",
+            source_family: :builtin
+          )
+        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.
+        def first_failure_clause(failure)
+          _, error_class, member, = failure
+          return " First failure: #{error_class}." if member.nil? || member.empty?
+
+          " First failure: #{error_class} on `#{member}`."
+        end
+
+        # Identical on a cache HIT: the ADR-54 env cache drops location POSITIONS but keeps each buffer's
+        # NAME, so a warm run names the same files a cold one does. Where a name is absent anyway, the
+        # reconstructed {RbsLoader::CACHED_LOCATION_BUFFER_NAME} sentinel is filtered out and the clause is
+        # omitted, rather than naming `<cached>` as if it were a path.
+        def conflicting_files_clause(files, sample_size)
+          return "" if files.empty?
+
+          " Conflicting signature file(s): #{sampled(files, sample_size)}."
+        end
+
+        # "a, b, c, and N more" — the sampling shape every `rbs.coverage.*` message above uses.
+        def sampled(names, sample_size)
+          sample = names.first(sample_size)
+          suffix = names.size > sample_size ? ", and #{names.size - sample_size} more" : ""
+          "#{sample.join(', ')}#{suffix}"
+        end
+
+        # Issue #784 — one `:error` row per run, unlike its two `:warning` `rbs.coverage.*` siblings above.
+        # Those two are typically a collision between the user's OWN `sig/` and Rigor's bundled RBS, so an
+        # `:error` default would let a Rigor release turn a green project red with zero user change (ADR-5
+        # / AGENTS.md § FP discipline) — the reason both stay `:warning` by default. This row has no such
+        # neighbour: post-#783 the scan itself raising is an ANALYZER defect, never something a user's
+        # `sig/` could trigger on its own, so there is no green project this could newly redden. And the
+        # run was already non-zero before this row existed — issue #784's seam is what stopped the raise
+        # from reaching every file as N identical `internal analyzer error` rows in the first place, and
+        # THAT per-file rescue is what `Result#success?` was already reading as a failure; this row only
+        # makes the reason legible.
+        #
+        # One row per RUN, not per file: the scan is one build over the whole `signature_paths:` overlay
+        # (memoised — see {Environment#hkt_registry}), so every file that would have demanded it hit the
+        # exact same failure, and a row per file would say the same thing N times.
+        #
+        # `:rbs_build` (via {CrashSignature::RBS_BUILD_FAILURE_RULES}), not `:check_rule`: the analysis ran
+        # to completion over a DEGRADED type universe — every rule still fired, unlike `:check_rule`'s
+        # whole-file replacement — so a consumer gating on {CrashSignature.discards_file_analysis?} must
+        # keep reading this run's diagnostics rather than refuse it as a crash.
+        def build_rbs_hkt_scan_failed_diagnostic(failure)
+          error_class, first_line, frame, stage = failure
+          relative_frame = CrashSignature.relativize_frame(frame)
+          frame_clause = relative_frame ? " at #{relative_frame}" : ""
+          raised = "(#{error_class}): #{first_line}#{frame_clause}."
+          Diagnostic.new(
+            path: ".rigor.yml",
+            line: 1,
+            column: 1,
+            message: stage == :overlay ? hkt_overlay_failed_message(raised) : hkt_scan_failed_message(raised),
+            severity: :error,
+            rule: "rbs.coverage.hkt-scan-failed",
+            source_family: :builtin
+          )
+        end
+
+        def hkt_scan_failed_message(raised)
+          "The implicit HKT scan over RBS `type` aliases raised #{raised} Rigor fell back to the bundled " \
+            "and plugin HKT registrations, so a recursive `type` alias in your `.rbs` or an installed " \
+            "`rbs collection` no longer registers as a type constructor and reads its bound " \
+            "(`Dynamic[top]`) instead — this run is quieter than it should be, not cleaner. " \
+            "This is an analyzer defect, not a problem with your signatures; please report it " \
+            "with the message above."
+        end
+
+        # Issue #791 — the overlay stage of the same build, worded for the plugin it came from. The scan
+        # wording would send a user to their `.rbs` for a defect that is not there: what failed is the
+        # aggregation of the loaded plugins' manifest-declared HKT entries, and the message names the
+        # plugin whenever the raise was attributable to one (`Plugin::Registry#hkt_overlay_registry` puts
+        # the id in the message it re-raises). The degradation is narrower than the scan's, so the fallback
+        # sentence differs too: only the plugin entries are missing, and the user's own `.rbs` scan still
+        # ran on top of the bundled registrations.
+        def hkt_overlay_failed_message(raised)
+          "Building the plugin HKT overlay raised #{raised} Rigor skipped every plugin-declared HKT " \
+            "registration and analysed with the bundled ones plus your own `.rbs` overlay, so a type " \
+            "constructor a plugin declares reads its bound (`Dynamic[top]`) instead — this run is " \
+            "quieter than it should be, not cleaner. This is a defect in the named plugin or in Rigor, " \
+            "not a problem with your signatures; report it with the message above, or remove the plugin " \
+            "from `plugins:` to analyse without it."
+        end
+
         # The absolute path is what the loader records; the user thinks in project-relative terms.
         def relative_signature_path(path)
           root = "#{Dir.pwd}#{File::SEPARATOR}"
@@ -515,16 +692,19 @@ module Rigor
         #   enable.
         # - `dynamic.shape.lossy-projection` for every shape-projection type function (`pick_of`, …) applied
         #   to a carrier that loses precision (anything other than `HashShape` / `Tuple`).
+        # - `dynamic.rbs-extended.hkt-directive-invalid` for every malformed ADR-20 `rigor:v1:hkt_register` /
+        #   `rigor:v1:hkt_define` the directive parser declined (issue #785).
         #
-        # Both are authored `:info`; the severity profile re-stamps them per project taste. Path / line /
-        # column come from the annotation's `RBS::Location` when available, falling back to
-        # `.rigor.yml`-style file-level attribution otherwise.
+        # All three are authored `:info`; the severity profile re-stamps them per project taste. Every stream
+        # carries its `(path, line, column)` already flattened off the annotation's `RBS::Location`, because
+        # all three cross the pool drain channel (see {RbsExtended::Reporter}); an entry with no position
+        # falls back to `.rigor.yml`-style file-level attribution.
         def rbs_extended_reporter_diagnostics
           return [] if @rbs_extended_reporter.empty?
 
           unresolved = @rbs_extended_reporter.unresolved_payloads.map do |entry|
-            build_reporter_diagnostic(
-              entry.source_location,
+            build_positioned_reporter_diagnostic(
+              entry,
               rule: "dynamic.rbs-extended.unresolved",
               message: "`RBS::Extended` directive payload could not be resolved: " \
                        "#{entry.payload.inspect}. Check for typos or enable a plugin " \
@@ -533,8 +713,8 @@ module Rigor
           end
 
           lossy = @rbs_extended_reporter.lossy_projections.map do |entry|
-            build_reporter_diagnostic(
-              entry.source_location,
+            build_positioned_reporter_diagnostic(
+              entry,
               rule: "dynamic.shape.lossy-projection",
               message: "Shape projection `#{entry.head}` applied to a carrier without a " \
                        "literal shape; the projection degrades to the input type. Author " \
@@ -542,7 +722,22 @@ module Rigor
             )
           end
 
-          unresolved + lossy
+          unresolved + lossy + hkt_directive_diagnostics
+        end
+
+        # Issue #785 — one row per declined HKT directive. The consequence sentence is the point: the parser
+        # is fail-soft, so nothing else in the run tells the author that the constructor they registered is
+        # not there and that every `App[…]` naming it silently reads its bound.
+        def hkt_directive_diagnostics
+          @rbs_extended_reporter.hkt_directive_errors.map do |entry|
+            build_positioned_reporter_diagnostic(
+              entry,
+              rule: "dynamic.rbs-extended.hkt-directive-invalid",
+              message: "`RBS::Extended` HKT directive was declined: #{entry.message}. The type " \
+                       "constructor stays unregistered, so an `App[...]` carrier naming it reads " \
+                       "its bound (`Dynamic[top]`) instead of the type function."
+            )
+          end
         end
 
         # ADR-32 WD6 — drains the per-run {Plugin::SourceRbsSynthesisReporter} into
@@ -624,6 +819,20 @@ module Rigor
           )
         end
 
+        # The {RbsExtended::Reporter} form of the builder above: its three streams carry the position as
+        # `(path, line, column)` primitives rather than as the `RBS::Location` a conformance record holds,
+        # because they cross the pool drain channel (#785, #805). A missing component falls back exactly as
+        # {#location_fields} does for a missing location.
+        def build_positioned_reporter_diagnostic(entry, rule:, message:)
+          path = entry.path.to_s
+          Diagnostic.new(
+            path: path.empty? ? ".rigor.yml" : path,
+            line: entry.line || 1,
+            column: entry.column || 1,
+            message: message, severity: :info, rule: rule, source_family: :builtin
+          )
+        end
+
         def location_fields(source_location)
           return [".rigor.yml", 1, 1] if source_location.nil?
 
@@ -684,6 +893,14 @@ module Rigor
           @env_build_failure_snapshot_reader.call
         end
 
+        def definition_build_failures_snapshot
+          @definition_build_failures_snapshot_reader.call
+        end
+
+        def hkt_scan_failure_snapshot
+          @hkt_scan_failure_snapshot_reader.call
+        end
+
         def conformance_results_snapshot
           @conformance_results_snapshot_reader.call
         end