rigortype 0.1.14 → 0.1.16

data/lib/rigor/analysis/rule_catalog.rb

@@ -288,6 +288,86 @@ module Rigor
           since: "0.1.2"
         ),
 
+        CheckRules::RULE_OVERRIDE_VISIBILITY_REDUCED => Entry.new(
+          id: CheckRules::RULE_OVERRIDE_VISIBILITY_REDUCED,
+          summary: "Instance-method override reduces the visibility it inherits from an ancestor.",
+          fires_when: [
+            "An instance `def` shadows a same-name instance method defined by a project-discovered " \
+            "ancestor (included/prepended module or superclass, cross-file).",
+            "The override's source-discovered visibility is strictly more restrictive than the " \
+            "ancestor's (public → protected/private, or protected → private).",
+            "Both visibilities are statically observable from project source."
+          ],
+          does_not_fire_when: [
+            "Override raises or preserves visibility (only reductions break substitutability).",
+            "The shadowed method lives on an RBS-known / third-party ancestor (RBS models only " \
+            "public/private; RBS-parent visibility is a deferred follow-on).",
+            "`def self.foo` singleton methods (visibility is instance-side only).",
+            "The `private def foo; end` wrap-around form (not yet tracked by the visibility walker)."
+          ],
+          suppression: "`# rigor:disable def.override-visibility-reduced` on the override.",
+          severity_authored: :warning,
+          severity_by_profile: { lenient: :off, balanced: :warning, strict: :error },
+          since: "0.1.15"
+        ),
+
+        CheckRules::RULE_OVERRIDE_RETURN_WIDENED => Entry.new(
+          id: CheckRules::RULE_OVERRIDE_RETURN_WIDENED,
+          summary: "Instance-method override widens the return type it inherits from an ancestor.",
+          fires_when: [
+            "An instance `def` with an authored RBS signature overrides a same-name method whose " \
+            "RBS signature is declared by a project-discovered ancestor (module or superclass).",
+            "The override's declared return is not acceptable where the ancestor's declared return " \
+            "is expected (`parent_return.accepts(override_return)` is `:no`) — a covariance violation."
+          ],
+          does_not_fire_when: [
+            "Either side lacks an authored RBS signature (WD1 both-sides-authored gate).",
+            "The override narrows or preserves the return (covariant-safe).",
+            "The ancestor's return is `untyped` / `self` / an unbound generic (degrades to " \
+            "`Dynamic[Top]`, which accepts everything — FP-safe).",
+            "The subtype relationship between the two return types is not resolvable from loaded " \
+            "Ruby classes / their ancestors (a user-only class hierarchy degrades to `:maybe` and " \
+            "stays silent — the check has reach over core / stdlib / loadable-gem hierarchies).",
+            "`def self.foo` singleton methods (instance-side only in v1).",
+            "The shadowed method lives only on an RBS-known / third-party ancestor not in the " \
+            "project-discovered chain (user-source ancestor scope in v1)."
+          ],
+          suppression: "`# rigor:disable def.override-return-widened` on the override.",
+          severity_authored: :warning,
+          severity_by_profile: { lenient: :off, balanced: :warning, strict: :error },
+          since: "0.1.15"
+        ),
+
+        CheckRules::RULE_OVERRIDE_PARAM_NARROWED => Entry.new(
+          id: CheckRules::RULE_OVERRIDE_PARAM_NARROWED,
+          summary: "Instance-method override narrows a parameter type it inherits from an ancestor.",
+          fires_when: [
+            "An instance `def` with an authored RBS signature overrides a same-name method whose " \
+            "RBS signature is declared by a project-discovered ancestor (module or superclass).",
+            "At some matching positional parameter index, the override's slot cannot accept the " \
+            "ancestor's parameter type (`override_param.accepts(parent_param)` is `:no`) — a " \
+            "contravariance violation (the override narrowed the parameter)."
+          ],
+          does_not_fire_when: [
+            "Either side lacks an authored RBS signature (WD1 both-sides-authored gate).",
+            "The override widens or preserves the parameter (contravariant-safe).",
+            "Either side is overloaded (more than one method type — arm mapping is ambiguous).",
+            "The ancestor's parameter is `untyped` / an unbound generic / an interface (degrades " \
+            "to `Dynamic[Top]`, which is passable to anything — FP-safe).",
+            "The subtype relationship between the two parameter types is not resolvable from loaded " \
+            "Ruby classes / their ancestors (a user-only class hierarchy degrades to `:maybe` and " \
+            "stays silent — the check has reach over core / stdlib / loadable-gem hierarchies).",
+            "Arity / keyword-requiredness divergence (out of scope for v1 — positional types only).",
+            "`def self.foo` singleton methods (instance-side only in v1).",
+            "The shadowed method lives only on an RBS-known / third-party ancestor (user-source " \
+            "ancestor scope in v1)."
+          ],
+          suppression: "`# rigor:disable def.override-param-narrowed` on the override.",
+          severity_authored: :warning,
+          severity_by_profile: { lenient: :off, balanced: :warning, strict: :error },
+          since: "0.1.15"
+        ),
+
         CheckRules::RULE_IVAR_WRITE_MISMATCH => Entry.new(
           id: CheckRules::RULE_IVAR_WRITE_MISMATCH,
           summary: "Same instance variable assigned a different concrete class within one class.",

data/lib/rigor/analysis/runner.rb

@@ -106,11 +106,15 @@ module Rigor
         # nil-guards.
         @class_decl_paths_snapshot = {}.freeze
         @signature_paths_snapshot = [].freeze
+        @synthesized_namespaces_snapshot = [].freeze
         @cached_plugin_prepare_diagnostics = [].freeze
         @project_discovered_classes = {}.freeze
         @project_discovered_def_nodes = {}.freeze
+        @project_discovered_def_sources = {}.freeze
         @project_discovered_superclasses = {}.freeze
         @project_discovered_includes = {}.freeze
+        @project_discovered_method_visibilities = {}.freeze
+        @project_discovered_methods = {}.freeze
       end
 
       # ADR-pending editor mode — present when the runner is wired
@@ -139,6 +143,7 @@ module Rigor
         expansion = expand_paths(paths)
         @class_decl_paths_snapshot = {}.freeze
         @signature_paths_snapshot = []
+        @synthesized_namespaces_snapshot = []
 
         if @prebuilt
           adopt_prebuilt_project_scan(@prebuilt)
@@ -148,6 +153,7 @@ module Rigor
 
         diagnostics = pre_file_diagnostics(expansion)
         diagnostics += analyze_files(target_files(expansion))
+        diagnostics += rbs_synthesized_namespace_diagnostics
         diagnostics += rbs_extended_reporter_diagnostics
         diagnostics += boundary_cross_diagnostics
         diagnostics += source_rbs_synthesis_diagnostics
@@ -257,8 +263,11 @@ module Rigor
         def_index =
           Inference::ScopeIndexer.discovered_def_index_for_paths(expansion.fetch(:files), buffer: @buffer)
         @project_discovered_def_nodes = def_index.fetch(:def_nodes)
+        @project_discovered_def_sources = def_index.fetch(:def_sources)
         @project_discovered_superclasses = def_index.fetch(:superclasses)
         @project_discovered_includes = def_index.fetch(:includes)
+        @project_discovered_method_visibilities = def_index.fetch(:method_visibilities)
+        @project_discovered_methods = def_index.fetch(:methods)
       end
 
       # Internal: adopts a frozen {ProjectScan} snapshot supplied
@@ -299,6 +308,16 @@ module Rigor
           dispatch_pool(files)
         else
           environment = resolve_sequential_environment(source_files: files)
+          # Snapshot the small synthesized-namespace name list (NOT the
+          # env — see the method comment) so #run can surface the
+          # malformed-RBS `:info` diagnostic without rebuilding the env.
+          # Gated on the project actually declaring `signature_paths:`:
+          # synthesis only matters for the project's own RBS, and
+          # `#synthesized_namespaces` forces the (otherwise-lazy) RBS env
+          # to build — doing so when there is no project sig set would
+          # warm `.rigor/cache` on a bare `--no-stats` run.
+          @synthesized_namespaces_snapshot =
+            project_signature_paths? ? (environment.rbs_loader&.synthesized_namespaces || []) : []
           result = files.flat_map { |path| analyze_file(path, environment) }
           if @collect_stats
             loader = environment.rbs_loader
@@ -1112,6 +1131,48 @@ module Rigor
         [build_rbs_coverage_missing_diagnostic(missing)]
       end
 
+      # Robustness uplift companion (ADR-5) — when the project's
+      # `signature_paths:` RBS declared qualified names without their
+      # enclosing namespace, `RbsLoader` synthesizes the missing
+      # `module`s so the otherwise-inert signatures resolve. Surface a
+      # single `:info` diagnostic naming them so the 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.
+      def rbs_synthesized_namespace_diagnostics
+        synthesized = @synthesized_namespaces_snapshot
+        return [] if synthesized.nil? || synthesized.empty?
+
+        [build_rbs_synthesized_namespace_diagnostic(synthesized)]
+      end
+
+      # True when the project declares its own `signature_paths:` (the
+      # only place the qualified-name-without-namespace mistake lives).
+      def project_signature_paths?
+        paths = @configuration.signature_paths
+        !(paths.nil? || paths.empty?)
+      end
+
+      def build_rbs_synthesized_namespace_diagnostic(synthesized)
+        sample_size = 5
+        sample = synthesized.first(sample_size)
+        suffix = synthesized.size > sample_size ? ", and #{synthesized.size - sample_size} more" : ""
+        Diagnostic.new(
+          path: ".rigor.yml",
+          line: 1,
+          column: 1,
+          message: "#{synthesized.size} RBS namespace(s) under `signature_paths:` are " \
+                   "referenced by qualified declarations (e.g. `class Foo::Bar`) but never " \
+                   "declared: #{sample.join(', ')}#{suffix}. `rbs validate` rejects this; " \
+                   "Rigor synthesized the missing `module`(s) so the signatures still " \
+                   "resolve. Declare each (`module <name>` / `class <name>`) in your RBS to " \
+                   "make the sig set valid upstream.",
+          severity: :info,
+          rule: "rbs.coverage.synthesized-namespace",
+          source_family: :builtin
+        )
+      end
+
       def build_rbs_coverage_missing_diagnostic(missing)
         sample_size = 5
         sample = missing.first(sample_size).map(&:gem_name)
@@ -1324,8 +1385,9 @@ module Rigor
       end
 
       def collect_plugin_diagnostics(plugin, path, root, scope)
-        raw = plugin.diagnostics_for_file(path: path, scope: scope, root: root)
-        Array(raw).map { |diagnostic| stamp_plugin_diagnostic(diagnostic, plugin.manifest.id) }
+        raw = Array(plugin.diagnostics_for_file(path: path, scope: scope, root: root))
+        raw += plugin.node_rule_diagnostics(path: path, scope: scope, root: root)
+        raw.map { |diagnostic| stamp_plugin_diagnostic(diagnostic, plugin.manifest.id) }
       rescue StandardError => e
         [plugin_runtime_error_diagnostic(path, plugin, e)]
       end
@@ -1449,10 +1511,17 @@ module Rigor
         unless @project_discovered_def_nodes.empty?
           scope = scope.with_discovered_def_nodes(@project_discovered_def_nodes)
         end
+        unless @project_discovered_def_sources.empty?
+          scope = scope.with_discovered_def_sources(@project_discovered_def_sources)
+        end
         unless @project_discovered_superclasses.empty?
           scope = scope.with_discovered_superclasses(@project_discovered_superclasses)
         end
         scope = scope.with_discovered_includes(@project_discovered_includes) unless @project_discovered_includes.empty?
+        unless @project_discovered_method_visibilities.empty?
+          scope = scope.with_discovered_method_visibilities(@project_discovered_method_visibilities)
+        end
+        scope = scope.with_discovered_methods(@project_discovered_methods) unless @project_discovered_methods.empty?
         scope
       end
 

data/lib/rigor/analysis/worker_session.rb

@@ -284,8 +284,9 @@ module Rigor
       end
 
       def collect_plugin_diagnostics(plugin, path, root, scope)
-        raw = plugin.diagnostics_for_file(path: path, scope: scope, root: root)
-        Array(raw).map { |diagnostic| stamp_plugin_diagnostic(diagnostic, plugin.manifest.id) }
+        raw = Array(plugin.diagnostics_for_file(path: path, scope: scope, root: root))
+        raw += plugin.node_rule_diagnostics(path: path, scope: scope, root: root)
+        raw.map { |diagnostic| stamp_plugin_diagnostic(diagnostic, plugin.manifest.id) }
       rescue StandardError => e
         [plugin_runtime_error_diagnostic(path, plugin, e)]
       end

data/lib/rigor/cache/descriptor.rb

@@ -26,8 +26,12 @@ module Rigor
       # mixes this into the cache key, so a bump implicitly
       # invalidates every cached value. v2 added the
       # `dependencies` slot for ADR-10 per-gem-version cache slice
-      # invalidation.
-      SCHEMA_VERSION = 2
+      # invalidation. v3: `RbsLoader.build_env_for` now synthesizes
+      # `module`s for namespaces a project's `signature_paths:` RBS
+      # references but never declares, so the marshalled RBS env
+      # cached by an older Rigor (which would leave those signatures
+      # inert) MUST be rebuilt for the synthesis to take effect.
+      SCHEMA_VERSION = 3
 
       # Per-slot entry value objects. Constructors validate enums /
       # required fields and freeze the resulting struct so no caller

data/lib/rigor/cli/plugin_command.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+module Rigor
+  class CLI
+    # `rigor plugin` (singular) — discover and read the plugin source
+    # bundled with the `rigortype` gem.
+    #
+    # Rigor ships ~30 production plugins under `plugins/` and a set of
+    # tutorial plugins under `examples/`. When Rigor is installed via
+    # `mise` / `gem install` the gem checkout is on disk, so a plugin
+    # author (or an AI coding agent following the `rigor-plugin-author`
+    # skill) can read a real, working plugin as a worked example —
+    # instead of guessing the `Rigor::Plugin::Base` surface from prose.
+    # This command outputs the absolute paths so they can be found and
+    # read regardless of where the gem landed.
+    #
+    # It is deliberately distinct from `rigor plugins` (plural), which
+    # reports the activation status of the plugins configured in *your*
+    # `.rigor.yml`. This command (singular) browses the plugins bundled
+    # in the *toolchain*. Mnemonic: "plugins" = my config; "plugin" =
+    # the catalogue I can learn from.
+    #
+    # Subcommands:
+    #
+    # - `rigor plugin list`          — every bundled plugin + example,
+    #                                  name + absolute directory path.
+    # - `rigor plugin path <name>`   — one-line absolute path to the
+    #                                  plugin's directory (Read-tool input).
+    # - `rigor plugin print <name>`  — a header (dir / lib / sig / README
+    #                                  paths) followed by the plugin's main
+    #                                  `lib/<name>.rb` source body.
+    # - `rigor plugin root`          — the rigortype gem root and its key
+    #                                  subdirectories (lib/, plugins/,
+    #                                  examples/, skills/, sig/), so an
+    #                                  author can read the public plugin
+    #                                  API (`lib/rigor/plugin.rb`) directly.
+    #
+    # `rigor plugin` with no subcommand is an alias for `list`.
+    #
+    # **Docker / cross-filesystem note.** Every path printed is resolved
+    # at runtime from this file's location, so it is correct *on the
+    # filesystem where `rigor` runs*. If you run `rigor` inside a
+    # container but read files from the host (or vice versa), the paths
+    # will not resolve — read them from the same environment that ran
+    # the command (`rigor plugin print` inlines the body for exactly
+    # this case: it works with no file-reading tool at all).
+    class PluginCommand
+      USAGE = <<~USAGE
+        Usage: rigor plugin <subcommand> [args]
+
+        Browse the plugins bundled in the rigortype toolchain (worked
+        examples for authoring your own). For the activation status of
+        the plugins in your .rigor.yml, use `rigor plugins` (plural).
+
+        Subcommands:
+          list                  List bundled + example plugins (default)
+          path  <name>          Print the absolute directory path of <name>
+          print <name>          Print <name>'s main lib source, with a header
+          root                  Print the gem root + key subdirectories
+
+        Examples:
+          rigor plugin list
+          rigor plugin path  rigor-activerecord
+          rigor plugin print rigor-activesupport-core-ext
+          rigor plugin root
+      USAGE
+
+      # The bundled plugins/examples/source live at `<gem_root>/...`.
+      # From `lib/rigor/cli/plugin_command.rb` the gem root is three
+      # directories up (matching SkillCommand::SKILLS_ROOT).
+      GEM_ROOT     = File.expand_path("../../..", __dir__)
+      PLUGINS_ROOT = File.join(GEM_ROOT, "plugins")
+      EXAMPLES_ROOT = File.join(GEM_ROOT, "examples")
+
+      def initialize(argv:, out: $stdout, err: $stderr)
+        @argv = argv
+        @out = out
+        @err = err
+      end
+
+      # @return [Integer] CLI exit status.
+      def run
+        subcommand = @argv.shift || "list"
+
+        case subcommand
+        when "list" then run_list
+        when "path" then run_path
+        when "print" then run_print
+        when "root" then run_root
+        when "-h", "--help", "help"
+          @out.puts(USAGE)
+          0
+        else
+          @err.puts("Unknown subcommand: #{subcommand}")
+          @err.puts(USAGE)
+          Rigor::CLI::EXIT_USAGE
+        end
+      end
+
+      private
+
+      def run_list
+        plugins = discover(PLUGINS_ROOT)
+        examples = discover(EXAMPLES_ROOT)
+        if plugins.empty? && examples.empty?
+          @err.puts("No bundled plugins found under #{PLUGINS_ROOT}")
+          return 1
+        end
+
+        width = (plugins + examples).map { |p| p.fetch(:name).length }.max
+        emit_group("Production plugins", PLUGINS_ROOT, plugins, width)
+        emit_group("Example plugins (tutorials)", EXAMPLES_ROOT, examples, width)
+        @out.puts
+        @out.puts("Engine source root: #{GEM_ROOT}")
+        @out.puts("  public plugin API: #{File.join(GEM_ROOT, 'lib/rigor/plugin.rb')}")
+        @out.puts(docker_note)
+        0
+      end
+
+      def emit_group(label, root, entries, width)
+        return if entries.empty?
+
+        @out.puts("#{label} — under #{root}:")
+        entries.each do |entry|
+          @out.puts(format("  %-#{width}s  %s", entry.fetch(:name), entry.fetch(:path)))
+        end
+      end
+
+      def run_path
+        name = @argv.shift
+        return usage_error("`path` requires a plugin name") if name.nil?
+
+        plugin = find(name)
+        return name_error(name) if plugin.nil?
+
+        @out.puts(plugin.fetch(:path))
+        0
+      end
+
+      def run_print
+        name = @argv.shift
+        return usage_error("`print` requires a plugin name") if name.nil?
+
+        plugin = find(name)
+        return name_error(name) if plugin.nil?
+
+        @out.puts(render_print_header(plugin))
+        @out.puts
+        entry = main_source_file(plugin)
+        if entry
+          @out.write(File.read(entry))
+        else
+          @out.puts("# (no lib/#{plugin.fetch(:name)}.rb entry file found; browse the directory above)")
+        end
+        0
+      end
+
+      def run_root
+        @out.puts("rigortype gem root: #{GEM_ROOT}")
+        {
+          "lib (engine source)" => File.join(GEM_ROOT, "lib"),
+          "lib/rigor/plugin.rb (public plugin API)" => File.join(GEM_ROOT, "lib/rigor/plugin.rb"),
+          "plugins (production plugins)" => PLUGINS_ROOT,
+          "examples (tutorial plugins)" => EXAMPLES_ROOT,
+          "skills (Agent Skills)" => File.join(GEM_ROOT, "skills"),
+          "sig (bundled RBS)" => File.join(GEM_ROOT, "sig")
+        }.each do |label, path|
+          marker = File.exist?(path) ? "" : "  (missing)"
+          @out.puts(format("  %<label>-42s %<path>s%<marker>s", label: label, path: path, marker: marker))
+        end
+        @out.puts(docker_note)
+        0
+      end
+
+      # The header that precedes the plugin body when an author runs
+      # `rigor plugin print <name>`. `# `-prefixed so the combined
+      # output stays readable; the Ruby body below it is unchanged.
+      def render_print_header(plugin)
+        dir = plugin.fetch(:path)
+        sig = File.join(dir, "sig")
+        readme = File.join(dir, "README.md")
+        <<~HEADER.chomp
+          # Rigor plugin: #{plugin.fetch(:name)}  (#{plugin.fetch(:kind)})
+          # Directory: #{dir}
+          # Lib:       #{File.join(dir, 'lib')}
+          # Sig:       #{File.directory?(sig) ? sig : '(none)'}
+          # README:    #{File.file?(readme) ? readme : '(none)'}
+          #
+          # A real, working plugin shipped with rigortype #{Rigor::VERSION}.
+          # The main source body is below; read the other files from the
+          # paths above. To suppress `call.undefined-method` for methods a
+          # DSL generates, study how an RBS-bundle plugin ships `sig/` (see
+          # `rigor plugin print rigor-activesupport-core-ext`).
+        HEADER
+      end
+
+      def discover(root)
+        return [] unless File.directory?(root)
+
+        kind = root == EXAMPLES_ROOT ? "example" : "production"
+        Dir.children(root).sort.filter_map do |name|
+          dir = File.join(root, name)
+          next unless File.directory?(dir)
+
+          { name: name, path: dir, kind: kind }
+        end
+      end
+
+      # Match the directory name with or without the conventional
+      # `rigor-` prefix, so both `rigor-activerecord` and
+      # `activerecord` resolve.
+      def find(name)
+        all = discover(PLUGINS_ROOT) + discover(EXAMPLES_ROOT)
+        all.find { |p| p.fetch(:name) == name } ||
+          all.find { |p| p.fetch(:name).delete_prefix("rigor-") == name.delete_prefix("rigor-") }
+      end
+
+      def main_source_file(plugin)
+        dir = plugin.fetch(:path)
+        candidate = File.join(dir, "lib", "#{plugin.fetch(:name)}.rb")
+        return candidate if File.file?(candidate)
+
+        Dir.glob(File.join(dir, "lib", "*.rb")).min
+      end
+
+      def docker_note
+        "\nNote: paths are local to where `rigor` runs. If you run rigor in a " \
+          "container,\nread these files from the same filesystem (use " \
+          "`rigor plugin print` to inline a body)."
+      end
+
+      def name_error(name)
+        @err.puts("Unknown plugin: #{name}")
+        @err.puts("Run `rigor plugin list` to see the bundled plugins.")
+        1
+      end
+
+      def usage_error(message)
+        @err.puts(message)
+        @err.puts(USAGE)
+        Rigor::CLI::EXIT_USAGE
+      end
+    end
+  end
+end

data/lib/rigor/cli/plugins_command.rb

@@ -32,7 +32,15 @@ module Rigor
     #   `trait_registries:` / `external_files:` /
     #   `type_node_resolvers:` / `hkt_registrations:` /
     #   `hkt_definitions:` / `protocol_contracts:` /
-    #   `source_rbs_synthesizer:`).
+    #   `source_rbs_synthesizer:`);
+    # - the ADR-37 narrow extension protocols read off the plugin
+    #   class — `node_rule` node types, `dynamic_return` receivers,
+    #   `type_specifier` methods.
+    #
+    # `--capabilities` switches to a focused catalogue of just the
+    # narrow-protocol gate values + produced/consumed facts (ADR-37
+    # § "Machine-readable capability catalogue") — the AI-legibility
+    # surface that lets an agent enumerate what every plugin does.
     #
     # Output formats: `text` (default, human-readable table) and
     # `json` (for tooling — SKILLs, CI gates, editor integrations).
@@ -52,7 +60,7 @@ module Rigor
     #   the RBS environment without conflict (requires constructing
     #   the Environment, which is heavier than the loader-only
     #   pass this slice does).
-    class PluginsCommand
+    class PluginsCommand # rubocop:disable Metrics/ClassLength
       USAGE = "Usage: rigor plugins [options]"
 
       def initialize(argv:, out: $stdout, err: $stderr)
@@ -69,7 +77,7 @@ module Rigor
         rows = build_rows(configuration)
 
         renderer = PluginsRenderer.new(rows: rows, configuration_path: config_path)
-        @out.puts(options.fetch(:format) == "json" ? renderer.json : renderer.text)
+        @out.puts(render(renderer, options))
 
         any_load_errors = rows.any? { |row| row.fetch(:status) == :load_error }
         return 1 if any_load_errors && options.fetch(:strict)
@@ -79,13 +87,32 @@ module Rigor
 
       private
 
+      # Picks the renderer view. `--capabilities` switches to the
+      # focused extension-protocol catalogue (ADR-37 § "Machine-readable
+      # capability catalogue") — per plugin, only the gate values that
+      # tell a reader (or an AI agent) exactly what the plugin
+      # contributes: the node-rule node types, the dynamic-return
+      # receivers, the type-specifier methods, and the produced /
+      # consumed facts. The default view stays the full activation report.
+      def render(renderer, options)
+        json = options.fetch(:format) == "json"
+        if options.fetch(:capabilities)
+          json ? renderer.capabilities_json : renderer.capabilities_text
+        else
+          json ? renderer.json : renderer.text
+        end
+      end
+
       def parse_options
-        options = { config: nil, format: "text", strict: false }
+        options = { config: nil, format: "text", strict: false, capabilities: false }
         OptionParser.new do |opts|
           opts.banner = USAGE
           opts.on("--config=PATH", "Path to the Rigor configuration file") { |v| options[:config] = v }
           opts.on("--format=FORMAT", "Output format: text (default) or json") { |v| options[:format] = v }
           opts.on("--strict", "Exit 1 if any plugin failed to load (CI gate)") { options[:strict] = true }
+          opts.on("--capabilities", "Emit the per-plugin extension-protocol catalogue (ADR-37)") do
+            options[:capabilities] = true
+          end
         end.parse!(@argv)
         validate!(options)
         options
@@ -165,9 +192,25 @@ module Rigor
         manifest = plugin.manifest
         identity_fields(gem_name, manifest, config)
           .merge(extension_fields(plugin, manifest))
+          .merge(narrow_protocol_fields(plugin))
           .merge(load_error: nil)
       end
 
+      # ADR-37 narrow extension protocols. Unlike the 10 declarative
+      # manifest fields, these are class-level DSLs (`node_rule` /
+      # `dynamic_return` / `type_specifier`), so they are read off the
+      # plugin class rather than the manifest. The gate values — node
+      # types, receiver class names, specified method names — are the
+      # greppable, enumerable surface the capability catalogue exposes.
+      def narrow_protocol_fields(plugin)
+        klass = plugin.class
+        {
+          node_rule_types: klass.node_rules.map { |r| r[:node_type].name }.uniq,
+          dynamic_return_receivers: klass.dynamic_returns.flat_map { |r| r[:receivers] }.uniq,
+          type_specifier_methods: klass.type_specifiers.flat_map { |r| r[:methods] }.map(&:to_s).uniq
+        }
+      end
+
       def identity_fields(gem_name, manifest, config)
         {
           gem: gem_name,
@@ -225,6 +268,9 @@ module Rigor
           hkt_definitions: 0,
           protocol_contracts: 0,
           source_rbs_synthesizer: false,
+          node_rule_types: [],
+          dynamic_return_receivers: [],
+          type_specifier_methods: [],
           load_error: error&.message || "plugin did not register or could not be matched to a registered class"
         }
       end
@@ -299,6 +345,7 @@ module Rigor
             external_files: 0, type_node_resolvers: 0,
             hkt_registrations: 0, hkt_definitions: 0,
             protocol_contracts: 0, source_rbs_synthesizer: false,
+            node_rule_types: [], dynamic_return_receivers: [], type_specifier_methods: [],
             load_error: error.message
           }
         end