rigortype 0.2.7 → 0.2.8

data/lib/rigor/analysis/rule_catalog.rb

@@ -4,53 +4,40 @@ require_relative "check_rules"
 
 module Rigor
   module Analysis
-    # Single-source-of-truth metadata table for every CheckRule
-    # the analyzer ships. Consumed by `rigor explain <rule>` so
-    # users can read the same information the docs site eventually
-    # publishes without leaving the terminal.
+    # Single-source-of-truth metadata table for every CheckRule the analyzer ships. Consumed by `rigor
+    # explain <rule>` so users can read the same information the docs site eventually publishes without
+    # leaving the terminal.
     #
     # Each entry carries:
     #
     # - `id` — canonical rule id (`call.undefined-method`).
     # - `summary` — single-line headline (≤ 80 chars).
-    # - `fires_when` — bullet-shaped list of conditions that
-    #   trigger the rule, in the order a reader can scan
-    #   top-to-bottom.
-    # - `does_not_fire_when` — explicit list of cases the rule
-    #   intentionally skips. Useful for "why am I NOT seeing
-    #   this diagnostic?" questions.
-    # - `suppression` — short note on how to suppress (in-source
-    #   `# rigor:disable` and the v0.1.2 file-scope variant
-    #   `# rigor:disable-file`, plus `.rigor.yml` `disable:`,
-    #   apply to every rule, so the note covers any rule-specific
-    #   nuance — e.g. unreachable-branch lives on the dead-branch
-    #   line, not the predicate line).
+    # - `fires_when` — bullet-shaped list of conditions that trigger the rule, in the order a reader can
+    #   scan top-to-bottom.
+    # - `does_not_fire_when` — explicit list of cases the rule intentionally skips. Useful for "why am I NOT
+    #   seeing this diagnostic?" questions.
+    # - `suppression` — short note on how to suppress (in-source `# rigor:disable` and the v0.1.2
+    #   file-scope variant `# rigor:disable-file`, plus `.rigor.yml` `disable:`, apply to every rule, so
+    #   the note covers any rule-specific nuance — e.g. unreachable-branch lives on the dead-branch line,
+    #   not the predicate line).
     # - `severity_authored` — Symbol the rule emits with.
-    # - `severity_by_profile` — Hash of `:lenient` / `:balanced`
-    #   / `:strict` to the configured severity per profile, taken
-    #   from `Configuration::SeverityProfile::PROFILES`.
-    # - `evidence_tier` — `:high` / `:medium` / `:low` (or `nil`
-    #   for informational helpers), Rigor's own confidence that a
-    #   firing is a true positive, derived from the rule's firing
-    #   gates. `:high` rules fire only on a concrete, statically-
-    #   known type with no metaprogramming escape (Rigor's false-
-    #   positive discipline has already filtered the uncertain
-    #   cases); `:medium` rules rest on flow / inference proofs
-    #   that inherit a documented FP envelope (loop / mutation /
-    #   RBS-strictness modelling gaps); `:low` rules are
-    #   resolution- or coverage-gap signals where a firing often
-    #   reflects missing context rather than a definite bug. The
-    #   tier routes a consumer's attention (and lets a downstream
-    #   classifier promote a `:high` firing without cross-tool
-    #   corroboration); it never feeds severity — that stays the
-    #   `severity_profile:` decision.
+    # - `severity_by_profile` — Hash of `:lenient` / `:balanced` / `:strict` to the configured severity per
+    #   profile, taken from `Configuration::SeverityProfile::PROFILES`.
+    # - `evidence_tier` — `:high` / `:medium` / `:low` (or `nil` for informational helpers), Rigor's own
+    #   confidence that a firing is a true positive, derived from the rule's firing gates. `:high` rules
+    #   fire only on a concrete, statically- known type with no metaprogramming escape (Rigor's
+    #   false-positive discipline has already filtered the uncertain cases); `:medium` rules rest on flow /
+    #   inference proofs that inherit a documented FP envelope (loop / mutation / RBS-strictness modelling
+    #   gaps); `:low` rules are resolution- or coverage-gap signals where a firing often reflects missing
+    #   context rather than a definite bug. The tier routes a consumer's attention (and lets a downstream
+    #   classifier promote a `:high` firing without cross-tool corroboration); it never feeds severity —
+    #   that stays the `severity_profile:` decision.
     # - `since` — first version the rule shipped in.
     module RuleCatalog # rubocop:disable Metrics/ModuleLength
-      # Stable documentation home for a built-in rule. `documentation_url`
-      # appends a per-rule fragment that resolves to the rule's anchor in
-      # the published diagnostics catalogue; the page itself points at
-      # `rigor explain <rule>` as the authoritative per-rule reference.
-      # Mirrors the gemspec `documentation_uri` URL scheme (`…/tree/main`).
+      # Stable documentation home for a built-in rule. `documentation_url` appends a per-rule fragment that
+      # resolves to the rule's anchor in the published diagnostics catalogue; the page itself points at
+      # `rigor explain <rule>` as the authoritative per-rule reference. Mirrors the gemspec
+      # `documentation_uri` URL scheme (`…/tree/main`).
       DOCUMENTATION_BASE = "https://github.com/rigortype/rigor/blob/main/docs/manual/04-diagnostics.md"
 
       class Entry < Data.define(:id, :summary, :fires_when, :does_not_fire_when,
@@ -65,10 +52,9 @@ module Rigor
           RuleCatalog.documentation_url(id)
         end
 
-        # Hash-shaped form for `--format=json` consumers. Keys are
-        # Strings so the payload is JSON-stable without a transform
-        # pass. `evidence_tier` is omitted when nil (informational
-        # helpers carry no confidence tier).
+        # Hash-shaped form for `--format=json` consumers. Keys are Strings so the payload is JSON-stable
+        # without a transform pass. `evidence_tier` is omitted when nil (informational helpers carry no
+        # confidence tier).
         def to_h
           base = {
             "id" => id,
@@ -131,11 +117,9 @@ module Rigor
                        "`severity_overrides: { call.self-undefined-method: warning }` in `.rigor.yml`.",
           severity_authored: :warning,
           severity_by_profile: { lenient: :off, balanced: :off, strict: :off },
-          # Off by default and metaprogramming-prone — a firing on a
-          # class whose real surface the per-class scan cannot enumerate
-          # (C-extension, `class << self`, dynamic accessors) is the
-          # known FP mode, so a firing is a candidate to review, not a
-          # high-confidence bug.
+          # Off by default and metaprogramming-prone — a firing on a class whose real surface the
+          # per-class scan cannot enumerate (C-extension, `class << self`, dynamic accessors) is the known
+          # FP mode, so a firing is a candidate to review, not a high-confidence bug.
           evidence_tier: :low,
           since: "0.1.17"
         ),
@@ -160,10 +144,9 @@ module Rigor
                        "file in `.rigor.yml`'s `pre_eval:` so the analyzer sees the top-level `def` / patch.",
           severity_authored: :warning,
           severity_by_profile: { lenient: :off, balanced: :warning, strict: :error },
-          # A firing is frequently a resolution gap — the defining file
-          # is not in the analyzed set or injects the method via a
-          # metaprogramming patch the analyzer does not see — rather than
-          # a definite typo, so it routes to the `pre_eval:` review path.
+          # A firing is frequently a resolution gap — the defining file is not in the analyzed set or
+          # injects the method via a metaprogramming patch the analyzer does not see — rather than a
+          # definite typo, so it routes to the `pre_eval:` review path.
           evidence_tier: :low,
           since: "0.1.14"
         ),
@@ -303,8 +286,8 @@ module Rigor
                        "points at the dead branch, not the predicate, so the suppression goes there).",
           severity_authored: :warning,
           severity_by_profile: { lenient: :info, balanced: :warning, strict: :error },
-          # The literal-only firing envelope makes the deadness provable
-          # from syntax alone — no inference uncertainty.
+          # The literal-only firing envelope makes the deadness provable from syntax alone — no inference
+          # uncertainty.
           evidence_tier: :high,
           since: "0.1.2"
         ),
@@ -328,10 +311,9 @@ module Rigor
           suppression: "`# rigor:disable always-truthy-condition` on the predicate line.",
           severity_authored: :warning,
           severity_by_profile: { lenient: :info, balanced: :warning, strict: :error },
-          # Rests on inferred-constant folding, which inherits the
-          # loop / mutation FP envelope the `does_not_fire_when` guards
-          # narrow — true positive in the common case, but not literal-
-          # provable like `unreachable-branch`.
+          # Rests on inferred-constant folding, which inherits the loop / mutation FP envelope the
+          # `does_not_fire_when` guards narrow — true positive in the common case, but not
+          # literal-provable like `unreachable-branch`.
           evidence_tier: :medium,
           since: "0.1.2"
         ),
@@ -355,11 +337,11 @@ module Rigor
           ],
           suppression: "`# rigor:disable unreachable-clause` on the dead-clause body line.",
           severity_authored: :warning,
-          # ADR-47 WD4: balanced stays :info (one notch below its `flow.*`
-          # siblings' :warning) until the regression-corpus FP gate is green.
+          # ADR-47 WD4: balanced stays :info (one notch below its `flow.*` siblings' :warning) until the
+          # regression-corpus FP gate is green.
           severity_by_profile: { lenient: :info, balanced: :info, strict: :warning },
-          # Narrowing-driven proof that inherits the `always-truthy`
-          # FP envelope; balanced keeps it `:info` pending the corpus gate.
+          # Narrowing-driven proof that inherits the `always-truthy` FP envelope; balanced keeps it `:info`
+          # pending the corpus gate.
           evidence_tier: :medium,
           since: "0.1.17"
         ),
@@ -382,10 +364,8 @@ module Rigor
           suppression: "`# rigor:disable dead-assignment` on the offending line, or rename the local to `_<name>`.",
           severity_authored: :warning,
           severity_by_profile: { lenient: :info, balanced: :warning, strict: :error },
-          # The unread-write proof is reliable, but it flags a code
-          # smell rather than a runtime fault, and the syntactic write
-          # classification has narrow corners (the `does_not_fire_when`
-          # exclusions).
+          # The unread-write proof is reliable, but it flags a code smell rather than a runtime fault, and
+          # the syntactic write classification has narrow corners (the `does_not_fire_when` exclusions).
           evidence_tier: :medium,
           since: "0.1.2"
         ),
@@ -408,9 +388,8 @@ module Rigor
           suppression: "`# rigor:disable def.return-type-mismatch`.",
           severity_authored: :warning,
           severity_by_profile: { lenient: :warning, balanced: :warning, strict: :error },
-          # Depends on re-typing the body against an authored RBS return;
-          # RBS strict-on-returns plus incomplete body inference makes a
-          # firing usually-right but not concrete-call certain.
+          # Depends on re-typing the body against an authored RBS return; RBS strict-on-returns plus
+          # incomplete body inference makes a firing usually-right but not concrete-call certain.
           evidence_tier: :medium,
           since: "0.1.0"
         ),
@@ -456,9 +435,8 @@ module Rigor
           suppression: "`# rigor:disable def.override-visibility-reduced` on the override.",
           severity_authored: :warning,
           severity_by_profile: { lenient: :off, balanced: :warning, strict: :error },
-          # Both the override and the shadowed ancestor visibility are
-          # statically observed from project source — the substitutability
-          # violation is concrete.
+          # Both the override and the shadowed ancestor visibility are statically observed from project
+          # source — the substitutability violation is concrete.
           evidence_tier: :high,
           since: "0.1.15"
         ),
@@ -487,8 +465,8 @@ module Rigor
           suppression: "`# rigor:disable def.override-return-widened` on the override.",
           severity_authored: :warning,
           severity_by_profile: { lenient: :off, balanced: :warning, strict: :error },
-          # Gated on both-sides-authored RBS and a resolvable subtype
-          # relationship, so a firing is a concrete covariance violation.
+          # Gated on both-sides-authored RBS and a resolvable subtype relationship, so a firing is a
+          # concrete covariance violation.
           evidence_tier: :high,
           since: "0.1.15"
         ),
@@ -520,8 +498,8 @@ module Rigor
           suppression: "`# rigor:disable def.override-param-narrowed` on the override.",
           severity_authored: :warning,
           severity_by_profile: { lenient: :off, balanced: :warning, strict: :error },
-          # Gated on both-sides-authored RBS and a resolvable subtype
-          # relationship, so a firing is a concrete contravariance violation.
+          # Gated on both-sides-authored RBS and a resolvable subtype relationship, so a firing is a
+          # concrete contravariance violation.
           evidence_tier: :high,
           since: "0.1.15"
         ),
@@ -544,8 +522,8 @@ module Rigor
           suppression: "`# rigor:disable ivar-write-mismatch` on the offending write.",
           severity_authored: :error,
           severity_by_profile: { lenient: :warning, balanced: :warning, strict: :error },
-          # Both writes resolve to concrete classes before firing; the
-          # union / Dynamic / clear-idiom escapes are excluded.
+          # Both writes resolve to concrete classes before firing; the union / Dynamic / clear-idiom
+          # escapes are excluded.
           evidence_tier: :high,
           since: "0.1.2"
         )
@@ -553,8 +531,7 @@ module Rigor
 
       module_function
 
-      # Looks up a rule by canonical id, legacy alias, or family
-      # wildcard. Returns an Array<Entry>:
+      # Looks up a rule by canonical id, legacy alias, or family wildcard. Returns an Array<Entry>:
       #
       # - canonical id → 1-element array,
       # - legacy alias → 1-element array (resolved to canonical),
@@ -580,12 +557,10 @@ module Rigor
         ENTRIES.values.sort_by(&:id)
       end
 
-      # Rigor's confidence tier (`:high` / `:medium` / `:low`) that a
-      # firing of `token` is a true positive, or nil for an
-      # informational rule (`dump.type`) or an unknown / non-built-in
-      # token (plugin and `rbs_extended.*` rules carry no built-in
-      # tier). Resolves legacy aliases. See {Entry}'s `evidence_tier`
-      # documentation for the tier semantics.
+      # Rigor's confidence tier (`:high` / `:medium` / `:low`) that a firing of `token` is a true positive,
+      # or nil for an informational rule (`dump.type`) or an unknown / non-built-in token (plugin and
+      # `rbs_extended.*` rules carry no built-in tier). Resolves legacy aliases. See {Entry}'s
+      # `evidence_tier` documentation for the tier semantics.
       def evidence_tier(token)
         entries = resolve(token)
         return nil unless entries.size == 1
@@ -593,12 +568,10 @@ module Rigor
         entries.first.evidence_tier
       end
 
-      # Stable documentation URL for `token`, or nil for an unknown /
-      # non-built-in token. The URL is the published diagnostics
-      # catalogue page anchored at the rule's per-rule anchor
-      # (`#rule-<id-with-dots-as-dashes>`); the page itself names
-      # `rigor explain <rule>` as the authoritative per-rule reference.
-      # Resolves legacy aliases to the canonical id.
+      # Stable documentation URL for `token`, or nil for an unknown / non-built-in token. The URL is the
+      # published diagnostics catalogue page anchored at the rule's per-rule anchor
+      # (`#rule-<id-with-dots-as-dashes>`); the page itself names `rigor explain <rule>` as the
+      # authoritative per-rule reference. Resolves legacy aliases to the canonical id.
       def documentation_url(token)
         entries = resolve(token)
         return nil unless entries.size == 1
@@ -606,9 +579,8 @@ module Rigor
         "#{DOCUMENTATION_BASE}##{doc_anchor(entries.first.id)}"
       end
 
-      # The per-rule fragment a `documentation_url` points at:
-      # `call.undefined-method` → `rule-call-undefined-method`. The
-      # `04-diagnostics.md` catalogue carries the matching `<a id>`
+      # The per-rule fragment a `documentation_url` points at: `call.undefined-method` →
+      # `rule-call-undefined-method`. The `04-diagnostics.md` catalogue carries the matching `<a id>`
       # anchors.
       def doc_anchor(rule_id)
         "rule-#{rule_id.tr('.', '-')}"

data/lib/rigor/analysis/run_stats.rb

@@ -4,35 +4,25 @@ require "rbconfig"
 
 module Rigor
   module Analysis
-    # End-of-run telemetry for the `rigor check` CLI's `--stats`
-    # output. Captures four cheap-to-measure groups:
+    # End-of-run telemetry for the `rigor check` CLI's `--stats` output. Captures four cheap-to-measure groups:
     #
-    # - **Check targets** — the Ruby files the analyser actually
-    #   walks for diagnostics (`expand_paths` output).
-    # - **Type universe** — RBS class/module declarations the
-    #   analyser had visibility of, broken down by source:
-    #   `project_sig` (declarations whose source file lives under
-    #   the configured `signature_paths`) vs `bundled` (RBS core,
-    #   stdlib libraries, gem-bundled RBS — everything outside
-    #   the project's own `sig/` tree).
-    # - **Gem source-walk** — the ADR-10
-    #   `dependencies.source_inference` catalogue. Reports the
-    #   class count and the number of opt-in gems contributing.
+    # - **Check targets** — the Ruby files the analyser actually walks for diagnostics (`expand_paths` output).
+    # - **Type universe** — RBS class/module declarations the analyser had visibility of, broken down by
+    #   source: `project_sig` (declarations whose source file lives under the configured `signature_paths`)
+    #   vs `bundled` (RBS core, stdlib libraries, gem-bundled RBS — everything outside the project's own
+    #   `sig/` tree).
+    # - **Gem source-walk** — the ADR-10 `dependencies.source_inference` catalogue. Reports the class count
+    #   and the number of opt-in gems contributing.
     # - **Process** — wall-clock seconds + peak resident set size.
     #
-    # The split between "check targets" and "type universe" makes
-    # explicit that the analyser's diagnostic surface is bounded
-    # by the user-controlled `paths:` configuration; the (typically
-    # much larger) RBS class universe is symbol-discovery, not a
-    # diagnostic surface.
+    # The split between "check targets" and "type universe" makes explicit that the analyser's diagnostic
+    # surface is bounded by the user-controlled `paths:` configuration; the (typically much larger) RBS
+    # class universe is symbol-discovery, not a diagnostic surface.
     #
-    # Stats collection is intentionally cheap: wall + RSS are
-    # single syscalls, target file count is already in
-    # `expand_paths`, gem source-walk uses
-    # `Index#class_to_gem.size`, and the RBS class breakdown
-    # walks `class_decl_paths` (a frozen `Hash<String, String>`
-    # populated once per environment by the RBS loader; ~1000-2000
-    # entries × one `String#start_with?`).
+    # Stats collection is intentionally cheap: wall + RSS are single syscalls, target file count is already
+    # in `expand_paths`, gem source-walk uses `Index#class_to_gem.size`, and the RBS class breakdown walks
+    # `class_decl_paths` (a frozen `Hash<String, String>` populated once per environment by the RBS loader;
+    # ~1000-2000 entries × one `String#start_with?`).
     class RunStats
       attr_reader :wall_seconds, :peak_rss_bytes,
                   :target_files,
@@ -56,13 +46,10 @@ module Rigor
         freeze
       end
 
-      # Reports the process's resident set size in bytes. Source
-      # ordering: `/proc/self/status` (Linux — reads `VmHWM:`,
-      # the peak RSS the kernel records) first; otherwise
-      # `ps -o rss= -p <pid>` (macOS / BSD — reports CURRENT
-      # RSS, the closest universally-available proxy). Returns
-      # nil when neither route works so the formatter can render
-      # `unavailable` instead of misleading zero.
+      # Reports the process's resident set size in bytes. Source ordering: `/proc/self/status` (Linux — reads
+      # `VmHWM:`, the peak RSS the kernel records) first; otherwise `ps -o rss= -p <pid>` (macOS / BSD —
+      # reports CURRENT RSS, the closest universally-available proxy). Returns nil when neither route works
+      # so the formatter can render `unavailable` instead of misleading zero.
       def self.peak_rss_bytes
         from_proc = read_vmhwm_from_proc
         return from_proc unless from_proc.nil?
@@ -96,22 +83,17 @@ module Rigor
         nil
       end
 
-      # Source-attribution sentinel produced by `RBS::Environment`
-      # entries restored from a cached blob (Marshal-loaded
-      # `RBS::Environment` loses real file-path attribution; every
-      # buffer reports `"<cached>"`). When every entry carries
-      # this sentinel the partition_classes routine returns
-      # `[0, total]` AND `attribution_available: false`, which
-      # the format routine consumes to suppress the misleading
-      # breakdown row.
+      # Source-attribution sentinel produced by `RBS::Environment` entries restored from a cached blob
+      # (Marshal-loaded `RBS::Environment` loses real file-path attribution; every buffer reports
+      # `"<cached>"`). When every entry carries this sentinel the partition_classes routine returns `[0,
+      # total]` AND `attribution_available: false`, which the format routine consumes to suppress the
+      # misleading breakdown row.
       CACHED_SENTINEL = "<cached>"
 
-      # Computes `(project_sig, bundled)` counts from a frozen
-      # `Hash<class_name => source_path>` snapshot and the
-      # configured `signature_paths`. `project_sig` is the count
-      # of classes whose source path begins with any of the
-      # signature path prefixes (after expansion to absolute
-      # paths); `bundled` is the remainder.
+      # Computes `(project_sig, bundled)` counts from a frozen `Hash<class_name => source_path>` snapshot and
+      # the configured `signature_paths`. `project_sig` is the count of classes whose source path begins
+      # with any of the signature path prefixes (after expansion to absolute paths); `bundled` is the
+      # remainder.
       def self.partition_classes(class_decl_paths:, signature_paths:)
         prefixes = Array(signature_paths).map { |p| File.expand_path(p.to_s) }
         return [0, class_decl_paths.size] if prefixes.empty?
@@ -124,33 +106,28 @@ module Rigor
         [project, class_decl_paths.size - project]
       end
 
-      # True when at least one entry in `class_decl_paths` carries
-      # a real source file path (i.e. not the cached-sentinel
-      # marker). Used by callers to decide whether the
-      # `project_sig` / `bundled` split is meaningful.
+      # True when at least one entry in `class_decl_paths` carries a real source file path (i.e. not the
+      # cached-sentinel marker). Used by callers to decide whether the `project_sig` / `bundled` split is
+      # meaningful.
       def self.attribution_available?(class_decl_paths:)
         return false if class_decl_paths.empty?
 
         class_decl_paths.each_value.any? { |path| path != CACHED_SENTINEL }
       end
 
-      # Writes a human-facing rendering of the stats to `out`
-      # (typically `$stderr` from the CLI). Format is intentionally
-      # plain text — JSON consumers should parse the structured
-      # output of `rigor check --format=json` and consult `stats`
-      # there.
+      # Writes a human-facing rendering of the stats to `out` (typically `$stderr` from the CLI). Format is
+      # intentionally plain text — JSON consumers should parse the structured output of `rigor check
+      # --format=json` and consult `stats` there.
       def format(out, prefix: "")
         out.puts("#{prefix}Check targets")
         out.puts("#{prefix}  Ruby source files: #{@target_files}")
         out.puts("#{prefix}Type universe (symbol discovery; not analyzed for diagnostics)")
         out.puts("#{prefix}  RBS classes available: #{@rbs_classes_total}")
         if @rbs_classes_total.zero?
-          # A normal run always loads the bundled core+stdlib RBS (~1300+
-          # classes), so zero means the environment failed to build (most
-          # often a duplicate declaration in `signature_paths:`) and fell
-          # back to empty — type coverage is then near-useless but the run
-          # still "succeeds". Surface it loudly so a broken setup is not
-          # read as a clean analysis (the 20260620 field trial: redmine
+          # A normal run always loads the bundled core+stdlib RBS (~1300+ classes), so zero means the
+          # environment failed to build (most often a duplicate declaration in `signature_paths:`) and fell
+          # back to empty — type coverage is then near-useless but the run still "succeeds". Surface it
+          # loudly so a broken setup is not read as a clean analysis (the 20260620 field trial: redmine
           # would otherwise wire a 0-coverage check into CI).
           out.puts("#{prefix}  WARNING: the RBS environment is empty — it failed to build or loaded no")
           out.puts("#{prefix}           signatures, so type coverage is severely limited (most diagnostics")