rigortype 0.1.4 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8142401ce01630e0adcc3e1d59dedfc0a123ae247617b7bf91d33cbffe4cb193
-  data.tar.gz: ca747bb44214c0bf7dca8203f1c2fcf84657b8a639dbdc5448ede1f32b3f48ae
+  metadata.gz: b5960ec17b35768103e97d752f8cc6fd78fcb3f12e12fc43dfa41be07ec5317b
+  data.tar.gz: e79c9b25c973c8938e9b2f0a2741cca5195342619827b320ca521ec09e54321e
 SHA512:
-  metadata.gz: 02ef30047bcbf17ee716634315664522449610396c0645cf2e9f289fab7b1bc5667ac60a3cbe4069b59c7435bc1ad2ff9142f35f525df019b439ef74ad58191b
-  data.tar.gz: 6e6fe48ffce033b46a1f44be6b2eff62c3e11733f6fd5a583a17e631e18a752d3b77464783da88e9c9f5f0ee345440ca5c751d05e3d77d5253334f3a988bbcf4
+  metadata.gz: af1e033a25410c0f87943f12d43ab18a3a0d2a79c01307c2117c2fc15be4c9db3cb28e6fec10ce598ef6a5bfa063227f280c023a0f7e9025b06c69946df4654d
+  data.tar.gz: 351b3275dd35f37a11d30a696627e23a6cdca31bfb94fa3eacae762d2de624e4a914c6f8f4eebdd7df0bd17fd9fac13fe55ac434957509b742771a00d352a981

data/README.md

@@ -421,11 +421,14 @@ analyzer guarantees live under
 with the [ADR-9](docs/adr/9-cross-plugin-api.md) cross-plugin
 fact channel (one plugin publishes a fact like `:model_index`,
 another consumes it), [ADR-11](docs/adr/11-sorbet-input-adapter.md)
-Sorbet ingestion, and [ADR-13](docs/adr/13-typenode-resolver-plugin.md)
-plugin-supplied type-vocabulary resolvers. **Nineteen worked
-examples** ship under [`examples/`](examples/) — each is a
-fully-shaped plugin gem with a runnable demo and an end-to-end
-integration spec.
+Sorbet ingestion, [ADR-13](docs/adr/13-typenode-resolver-plugin.md)
+plugin-supplied type-vocabulary resolvers, and
+[ADR-16](docs/adr/16-macro-expansion.md) macro / DSL expansion
+substrate (declarative Tier A block-as-method / Tier B
+trait-inlining-registry / Tier C heredoc-template / Tier D
+external-file inclusion). **Twenty-four worked examples** ship
+under [`examples/`](examples/) — each is a fully-shaped plugin
+gem with a runnable demo and an end-to-end integration spec.
 
 **Plugin-contract teaching examples** (focus on a single
 extension-point):
@@ -448,6 +451,25 @@ extension-point):
   (`Pick` / `Omit` / `Partial` / `Required` / `Readonly`) onto
   Rigor's shape-projection type functions.
 
+**Macro expansion substrate consumers** (ADR-16 — declarative
+manifest entries, no walker code):
+
+- [`rigor-sinatra`](examples/rigor-sinatra/) — **Tier A**
+  block-as-method. Recognises Sinatra's nine class-level HTTP
+  verb methods and narrows the route block's `self_type` so
+  bare `params` / `redirect` / `halt` resolve through
+  `Sinatra::Base`'s RBS.
+- [`rigor-dry-struct`](examples/rigor-dry-struct/) — **Tier C**
+  heredoc-template. Synthesises a reader on every `Dry::Struct`
+  subclass for each `attribute :name, T` / `attribute? :name, T`
+  call.
+- [`rigor-devise`](examples/rigor-devise/) — **Tier B**
+  trait-inlining registry mirroring `lib/devise/modules.rb`.
+  Each `devise :strategy_a, :strategy_b` call explodes the
+  included module's RBS instance methods onto the calling model
+  class (Devise's `user.valid_password?` returns the module's
+  authored `bool`).
+
 **Rails ecosystem plugins** (Tier 1 + Tier 2 + Tier 3 + Sorbet):
 
 - Tier 1: [`rigor-rails-routes`](examples/rigor-rails-routes/),
@@ -510,15 +532,15 @@ Common knobs the file exposes:
 
 ## Status
 
-Current released version: **`v0.1.2`**. The analyzer is usable
+Current released version: **`v0.1.4`**. The analyzer is usable
 on real Ruby code today; the rule catalogue is deliberately
 narrow — Rigor's stance is to surface zero false positives
-while the inference surface stabilises. The roadmap is tracked
-in [`docs/MILESTONES.md`](docs/MILESTONES.md); release-by-release
-detail lives in [`CHANGELOG.md`](CHANGELOG.md).
+while the inference surface stabilises. Forward-looking commitments
+(in-flight cycle + queued work) live in
+[`docs/ROADMAP.md`](docs/ROADMAP.md); the release-by-release
+"what shipped" record is [`CHANGELOG.md`](CHANGELOG.md).
 
-`v0.1.4` is the active development cluster on `master` and
-delivers:
+`v0.1.4` (released 2026-05-14) delivered:
 
 - **[ADR-10](docs/adr/10-dependency-source-inference.md) closed
   end-to-end** — opt-in gem-source inference, per-gem budget,
@@ -553,10 +575,15 @@ delivers:
   `rigor-activerecord` publishing `:model_index` via the
   ADR-9 cross-plugin fact channel.
 
-Nineteen worked plugin examples now ship under
+Twenty-four worked plugin examples now ship under
 [`examples/`](examples/) — see
 [`examples/README.md`](examples/README.md) for the comparison
-table.
+table. The current `[Unreleased]` cycle on `master` (release
+pending) also delivered the [ADR-16](docs/adr/16-macro-expansion.md)
+macro / DSL expansion substrate (four-tier declarative
+manifest contract + engine integration + Tier B/C precision
+promotion); see `CHANGELOG.md` `[Unreleased]` for the full
+landing notes.
 
 ## Contributing
 

data/lib/rigor/analysis/fact_store.rb

@@ -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: [])
@@ -136,6 +141,13 @@ module Rigor
 
         [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/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