rigortype 0.1.3 → 0.1.5

data/lib/rigor/analysis/diagnostic.rb

@@ -24,10 +24,8 @@ module Rigor
       # ADR-2 § "Plugin Diagnostic Provenance") let consumers
       # distinguish where a diagnostic originated without committing
       # to the plugin API itself.
-      # rubocop:disable Metrics/ParameterLists
       def initialize(path:, line:, column:, message:, severity: :error, rule: nil,
                      source_family: DEFAULT_SOURCE_FAMILY)
-        # rubocop:enable Metrics/ParameterLists
         @path = path
         @line = line
         @column = column

data/lib/rigor/analysis/fact_store.rb

@@ -18,7 +18,7 @@ module Rigor
         relational
       ].freeze
 
-      Target = Data.define(:kind, :name) do
+      class Target < Data.define(:kind, :name)
         def self.local(name)
           new(kind: :local, name: name.to_sym)
         end
@@ -28,7 +28,7 @@ module Rigor
         end
       end
 
-      Fact = Data.define(:bucket, :target, :predicate, :payload, :polarity, :stability) do
+      class Fact < Data.define(:bucket, :target, :predicate, :payload, :polarity, :stability)
         def initialize(bucket:, target:, predicate:, payload: nil, polarity: :positive, stability: :local_binding)
           bucket = bucket.to_sym
           raise ArgumentError, "unknown fact bucket #{bucket.inspect}" unless BUCKETS.include?(bucket)
@@ -47,9 +47,14 @@ module Rigor
       attr_reader :facts
 
       class << self
-        def empty
-          @empty ||= new
-        end
+        # ADR-15 Phase 4b.x — return the eagerly-loaded
+        # singleton-class `@empty` ivar. Lazy `@empty ||= new`
+        # would write to a class/module ivar from non-main
+        # Ractors and trip `Ractor::IsolationError`. The
+        # `@empty = new.freeze` at module body below
+        # pre-populates the ivar on the main Ractor at load
+        # time.
+        attr_reader :empty
       end
 
       def initialize(facts: [])
@@ -125,9 +130,24 @@ module Rigor
         unique.freeze
       end
 
+      # `fact.target` is `Target | Array[Target]` per the carrier
+      # contract. Branching with an early return on the `Array`
+      # arm lets type narrowing collapse the post-return value to
+      # the bare `Target` case, so the wrapped tuple is `[Target]`
+      # and the union of return paths is exactly `Array[Target]`.
       def fact_targets(fact)
-        Array(fact.target)
+        target = fact.target
+        return target if target.is_a?(Array)
+
+        [target]
       end
+
+      # ADR-15 Phase 4b.x — eager-load the singleton `@empty`
+      # on the main Ractor at module-load time. Workers then
+      # READ the populated ivar without ever attempting a
+      # class/module ivar WRITE (which non-main Ractors are
+      # forbidden from doing).
+      @empty = new.freeze
     end
   end
 end

data/lib/rigor/analysis/result.rb

@@ -3,10 +3,16 @@
 module Rigor
   module Analysis
     class Result
-      attr_reader :diagnostics
+      attr_reader :diagnostics, :stats
 
-      def initialize(diagnostics: [])
+      # @param stats [Rigor::Analysis::RunStats, nil] end-of-run
+      #   telemetry (target file count, RBS class breakdown,
+      #   wall + RSS) collected by the Runner. Nil when stats
+      #   collection wasn't requested or wasn't applicable
+      #   (early-exit paths like `validate_target_ruby` failure).
+      def initialize(diagnostics: [], stats: nil)
         @diagnostics = diagnostics
+        @stats = stats
       end
 
       def success?
@@ -18,11 +24,13 @@ module Rigor
       end
 
       def to_h
-        {
+        hash = {
           "success" => success?,
           "error_count" => error_count,
           "diagnostics" => diagnostics.map(&:to_h)
         }
+        hash["stats"] = @stats.to_h if @stats
+        hash
       end
     end
   end

data/lib/rigor/analysis/rule_catalog.rb

@@ -31,8 +31,8 @@ module Rigor
     #   from `Configuration::SeverityProfile::PROFILES`.
     # - `since` — first version the rule shipped in.
     module RuleCatalog # rubocop:disable Metrics/ModuleLength
-      Entry = Data.define(:id, :summary, :fires_when, :does_not_fire_when,
-                          :suppression, :severity_authored, :severity_by_profile, :since) do
+      class Entry < Data.define(:id, :summary, :fires_when, :does_not_fire_when,
+                                :suppression, :severity_authored, :severity_by_profile, :since)
         def aliases
           CheckRules::LEGACY_RULE_ALIASES.select { |_legacy, canonical| canonical == id }.keys
         end

data/lib/rigor/analysis/run_stats.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+
+module Rigor
+  module Analysis
+    # 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.
+    # - **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.
+    #
+    # 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,
+                  :rbs_classes_total, :rbs_classes_project_sig, :rbs_classes_bundled,
+                  :gem_walk_classes, :gem_walk_gems, :rbs_attribution_available
+
+      def initialize(wall_seconds:, peak_rss_bytes:, # rubocop:disable Metrics/ParameterLists
+                     target_files:,
+                     rbs_classes_total:, rbs_classes_project_sig:, rbs_classes_bundled:,
+                     gem_walk_classes:, gem_walk_gems:,
+                     rbs_attribution_available: true)
+        @wall_seconds = wall_seconds
+        @peak_rss_bytes = peak_rss_bytes
+        @target_files = target_files
+        @rbs_classes_total = rbs_classes_total
+        @rbs_classes_project_sig = rbs_classes_project_sig
+        @rbs_classes_bundled = rbs_classes_bundled
+        @gem_walk_classes = gem_walk_classes
+        @gem_walk_gems = gem_walk_gems
+        @rbs_attribution_available = rbs_attribution_available
+        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.
+      def self.peak_rss_bytes
+        from_proc = read_vmhwm_from_proc
+        return from_proc unless from_proc.nil?
+
+        from_ps = read_rss_via_ps
+        return from_ps unless from_ps.nil?
+
+        nil
+      end
+
+      def self.read_vmhwm_from_proc
+        return nil unless File.readable?("/proc/self/status")
+
+        File.foreach("/proc/self/status") do |line|
+          next unless line.start_with?("VmHWM:")
+
+          kb_token = line.split.find { |token| token.match?(/\A\d+\z/) }
+          return Integer(kb_token) * 1024 if kb_token
+        end
+        nil
+      rescue StandardError
+        nil
+      end
+
+      def self.read_rss_via_ps
+        out = `ps -o rss= -p #{Process.pid} 2>/dev/null`.strip
+        return nil if out.empty?
+
+        Integer(out) * 1024
+      rescue StandardError
+        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.
+      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.
+      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?
+
+        project = 0
+        class_decl_paths.each_value do |path|
+          expanded = File.expand_path(path)
+          project += 1 if prefixes.any? { |prefix| expanded.start_with?("#{prefix}/") || expanded == prefix }
+        end
+        [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.
+      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.
+      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_attribution_available
+          out.puts("#{prefix}    project sig/:        #{@rbs_classes_project_sig}")
+          out.puts("#{prefix}    bundled (core+stdlib+gems): #{@rbs_classes_bundled}")
+        elsif @rbs_classes_total.positive?
+          out.puts("#{prefix}    (source attribution unavailable on cache-hit runs; --no-cache surfaces it)")
+        end
+        if @gem_walk_gems.positive?
+          out.puts("#{prefix}  Gem source-walk classes: #{@gem_walk_classes} " \
+                   "(across #{@gem_walk_gems} #{@gem_walk_gems == 1 ? 'gem' : 'gems'} " \
+                   "via dependencies.source_inference)")
+        end
+        out.puts("#{prefix}Process")
+        out.puts("#{prefix}  Wall time:   #{Kernel.format('%.2fs', @wall_seconds)}")
+        out.puts("#{prefix}  Memory peak: #{format_bytes(@peak_rss_bytes)}")
+      end
+
+      def to_h
+        {
+          target_files: @target_files,
+          rbs_classes_total: @rbs_classes_total,
+          rbs_classes_project_sig: @rbs_classes_project_sig,
+          rbs_classes_bundled: @rbs_classes_bundled,
+          rbs_attribution_available: @rbs_attribution_available,
+          gem_walk_classes: @gem_walk_classes,
+          gem_walk_gems: @gem_walk_gems,
+          wall_seconds: @wall_seconds,
+          peak_rss_bytes: @peak_rss_bytes
+        }
+      end
+
+      private
+
+      def format_bytes(bytes)
+        return "unavailable" if bytes.nil?
+
+        units = %w[B KB MB GB TB]
+        size = bytes.to_f
+        index = 0
+        while size >= 1024 && index < units.size - 1
+          size /= 1024
+          index += 1
+        end
+        Kernel.format("%<size>.1f %<unit>s", size: size, unit: units[index])
+      end
+    end
+  end
+end