rigortype 0.3.2 → 0.3.4

data/lib/rigor/cli/effects_snapshot_command.rb

@@ -0,0 +1,256 @@
+# frozen_string_literal: true
+
+require "optionparser"
+
+require_relative "../analysis/runner"
+require_relative "../cache/store"
+require_relative "../configuration"
+require_relative "../effects/discharge"
+require_relative "../effects/path_finder"
+require_relative "../effects/snapshot"
+require_relative "../effects/snapshot_diff"
+require_relative "command"
+require_relative "effects_diff_renderer"
+require_relative "effects_explain_renderer"
+require_relative "options"
+
+module Rigor
+  class CLI
+    # ADR-103 WD7 — the snapshot verbs of `rigor effects`: `update`, `check`, `diff` and `explain`.
+    #
+    #   rigor effects update                  # write .rigor-effects.yml; commit it
+    #   rigor effects check                   # 0 fresh, 1 drift — the CI gate
+    #   rigor effects diff --baseline PATH    # the same comparison, never gating
+    #   rigor effects explain --symbol KEY    # the shortest edge path behind a reach change
+    #
+    # None of them emits a diagnostic or enters `rigor check`'s stream: drift between two observations by
+    # the same tool is 100 % precise, and whether it *matters* is the reviewer's judgment — which is
+    # exactly what makes it a review artefact rather than a finding
+    # ([ADR-102](../adr/102-unused-code-reachability-report.md)).
+    #
+    # **The verbs take no paths.** The report does (`rigor effects lib/foo.rb`), because a report is a
+    # view; a snapshot is a record of the whole project, and one written over a subset would read as a
+    # project where every other method vanished. The analysed set is always the configured `paths:`.
+    class EffectsSnapshotCommand < Command
+      VERBS = %w[update check diff explain].freeze
+
+      FORMATS = %w[text json].freeze
+      private_constant :FORMATS
+
+      # The verbs that read a committed record, and so accept `--baseline PATH` —
+      # `--baseline <(git show origin/main:.rigor-effects.yml)` is the bot form.
+      COMPARING_VERBS = %w[check diff explain].freeze
+      private_constant :COMPARING_VERBS
+
+      def initialize(argv:, verb:, out: $stdout, err: $stderr)
+        super(argv: argv, out: out, err: err)
+        @verb = verb
+      end
+
+      # @return [Integer] 0 fresh / written, 1 on drift under `check`, 64 on a usage error.
+      def run
+        options = parse_options
+        return usage_error("unsupported format: #{options.fetch(:format)}") unless
+          FORMATS.include?(options[:format])
+        return usage_error("rigor effects #{@verb} takes no paths; it records the configured paths:") unless
+          @argv.empty?
+
+        execute(options)
+      rescue OptionParser::ParseError => e
+        usage_error(e.message)
+      end
+
+      private
+
+      def execute(options)
+        configuration = Configuration.load(options.fetch(:config)).with_effects_enabled
+        current = build_snapshot(configuration, full: options.fetch(:full))
+        return write(configuration, current) if @verb == "update"
+
+        compare(configuration, current, options)
+      end
+
+      # ---- update -------------------------------------------------
+
+      # Always writes — there is no generate / regenerate split, because a snapshot has no "already
+      # exists" hazard: it records observations, so overwriting it is the whole point of running it.
+      def write(configuration, snapshot)
+        path = configuration.effects_snapshot_path
+        File.write(path, snapshot.to_yaml)
+        @err.puts("rigor: wrote #{path} (#{snapshot.methods.size} method(s), #{snapshot.reach.size} reach entr" \
+                  "#{snapshot.reach.size == 1 ? 'y' : 'ies'})")
+        @err.puts("rigor: note — `effects.snapshot.reach:` is empty, so the snapshot records `methods:` only.") if
+          configuration.effects_snapshot_reach.empty?
+        0
+      end
+
+      # ---- check / diff / explain ---------------------------------
+
+      def compare(configuration, current, options)
+        path = options.fetch(:baseline) || configuration.effects_snapshot_path
+        recorded = load_recorded(path)
+        return CLI::EXIT_USAGE if recorded == :error
+
+        discharge = options.fetch(:no_tolerated) ? Effects::Discharge.none : effect_discharge(configuration)
+        diff = Effects::SnapshotDiff.compare(
+          recorded: recorded, current: current,
+          tolerated: options.fetch(:no_tolerated) ? [] : configuration.effects_tolerated,
+          gate: configuration.effects_snapshot_gate,
+          strict_tolerated: options.fetch(:strict_tolerated),
+          undischarged: Effects::Snapshot.undischarged_index(
+            snapshot: current, table: @table, discharge: discharge
+          )
+        )
+        return explain(diff, options) if @verb == "explain"
+
+        EffectsDiffRenderer.new(out: @out, path: path).render(diff, format: options.fetch(:format))
+        @verb == "check" && diff.drift? ? 1 : 0
+      end
+
+      def effect_discharge(configuration)
+        Effects::Discharge.new(configuration.effects_tolerated)
+      end
+
+      # A missing snapshot is drift with a routed message, not an error: it is the state every project is
+      # in before its first `update`, and the fix is one command away.
+      def load_recorded(path)
+        return nil unless File.exist?(path)
+
+        Effects::Snapshot.load(path)
+      rescue Effects::Snapshot::ParseError => e
+        @err.puts("rigor: effect snapshot load failed: #{path}: #{e.message}")
+        :error
+      end
+
+      # ---- explain ------------------------------------------------
+
+      def explain(diff, options)
+        rows = options.fetch(:symbol) ? rows_for_symbol(options.fetch(:symbol)) : rows_for_changes(diff)
+        EffectsExplainRenderer.new(out: @out).render(rows, format: options.fetch(:format))
+        0
+      end
+
+      def rows_for_symbol(symbol)
+        entry = @table[symbol]
+        if entry.nil?
+          @err.puts("rigor: no effect unit named #{symbol}")
+          return []
+        end
+
+        reach_rows(symbol, entry.proven.to_a) + method_rows(symbol, entry.direct.proven.to_a)
+      end
+
+      # Every label a change introduced, explained once: a `reach:` change gets its shortest edge path, a
+      # `methods:` change gets the origin in the method's own body.
+      def rows_for_changes(diff)
+        diff.events.flat_map do |event|
+          labels = labels_of(event)
+          next [] if labels.empty?
+
+          event.table == "reach" ? reach_rows(event.symbol, labels) : method_rows(event.symbol, labels)
+        end.uniq
+      end
+
+      def labels_of(event)
+        return [event.label] if event.label
+        return [] unless event.category == Effects::SnapshotDiff::SYMBOL_ADDED
+
+        entry = @table[event.symbol]
+        entry ? entry.proven.to_a : []
+      end
+
+      def reach_rows(symbol, labels)
+        labels.filter_map do |label|
+          path = Effects::PathFinder.shortest(@table, symbol: symbol, label: label)
+          next if path.nil?
+
+          EffectsExplainRenderer::Row.new(table: "reach", symbol: symbol, label: label,
+                                          path: path.to_a, origin: path.origin)
+        end
+      end
+
+      def method_rows(symbol, labels)
+        entry = @table[symbol]
+        return [] if entry.nil?
+
+        labels.filter_map do |label|
+          origin = entry.direct.bundles.find { |_origin, set| set.include?(label) }&.first
+          next if origin.nil?
+
+          EffectsExplainRenderer::Row.new(table: "methods", symbol: symbol, label: label,
+                                          path: [].freeze, origin: origin.to_s)
+        end
+      end
+
+      # ---- the run ------------------------------------------------
+
+      # Same run the report takes: collection forced on for this invocation, sequential, and going through
+      # the ADR-45 whole-run result cache like `rigor check` — the diagnostics entry plus the #382 effects
+      # sidecar keyed beside it, so `rigor effects check` after `rigor check` under a configured `effects:`
+      # block is a warm hit plus the fixpoint.
+      def build_snapshot(configuration, full:)
+        runner = Analysis::Runner.new(
+          configuration: configuration,
+          cache_store: Cache::Store.new(root: configuration.cache_path),
+          collect_stats: false,
+          workers: 0
+        )
+        runner.run(configuration.paths)
+        @table = runner.effect_table
+        Effects::Snapshot.build(
+          table: @table, configuration: configuration, sources: runner.effect_sources, full: full,
+          registry: Effects::Registry.for_configuration(configuration,
+                                                        plugin_facts: runner.effect_plugin_facts)
+        )
+      end
+
+      # ---- options ------------------------------------------------
+
+      def parse_options
+        options = { config: nil, format: "text", full: false, baseline: nil, symbol: nil,
+                    strict_tolerated: false, no_tolerated: false }
+        OptionParser.new do |opts|
+          opts.banner = "Usage: rigor effects #{@verb} [options]"
+          Options.add_config(opts, options)
+          add_common_options(opts, options)
+          add_comparison_options(opts, options) if COMPARING_VERBS.include?(@verb)
+          if @verb == "explain"
+            opts.on("--symbol=KEY", "Explain this unit instead of the changed ones") do |value|
+              options[:symbol] = value
+            end
+          end
+        end.parse!(@argv)
+        options
+      end
+
+      # The policy switches are accepted by every verb, `update` included, and there they are deliberately
+      # inert: the record is **undischarged**, so `update --no-tolerated-effects` and `update` write
+      # byte-identical files. A flag that changed the record would make the file a function of policy and
+      # a policy change indistinguishable from a code change.
+      def add_common_options(opts, options)
+        opts.on("--format=FORMAT", "Output format: text (default) or json") { |value| options[:format] = value }
+        opts.on("--full", "Record every method, including the omitted trivial and synthesised ones") do
+          options[:full] = true
+        end
+        opts.on("--strict-tolerated", "Fail the gate on tolerated changes too (check / diff)") do
+          options[:strict_tolerated] = true
+        end
+        opts.on("--no-tolerated-effects", "Judge as if effects.tolerated: were empty (check / diff)") do
+          options[:no_tolerated] = true
+        end
+      end
+
+      def add_comparison_options(opts, options)
+        opts.on("--baseline=PATH", "Compare against PATH instead of effects.snapshot.path") do |value|
+          options[:baseline] = value
+        end
+      end
+
+      def usage_error(message)
+        @err.puts(message)
+        @err.puts("Usage: rigor effects #{@verb} [options]")
+        CLI::EXIT_USAGE
+      end
+    end
+  end
+end

data/lib/rigor/cli/unused_command.rb

@@ -0,0 +1,288 @@
+# frozen_string_literal: true
+
+require "optionparser"
+require "json"
+
+require_relative "../configuration"
+require_relative "../analysis/path_expansion"
+require_relative "../analysis/reachability/scan"
+require_relative "../analysis/reachability/graph"
+require_relative "../analysis/reachability/plugin_roots"
+require_relative "../analysis/reachability/signature_scan"
+require_relative "../analysis/reachability/project_files"
+require_relative "options"
+require_relative "command"
+require_relative "probe_environment"
+
+module Rigor
+  class CLI
+    # ADR-102 — executes `rigor unused`.
+    #
+    # Reports project constants that nothing reachable references. It is a REPORT, never a diagnostic: the
+    # measured precision of this signal is 7.0% on an adjudicated corpus target
+    # (`docs/notes/20260813-unused-constant-fp-baseline.md`), so its output is a review queue, not a defect
+    # list, and it never enters `rigor check`'s stream at any severity (WD1). Exits 0 whatever it finds.
+    class UnusedCommand < Command
+      USAGE = "Usage: rigor unused [options] [paths]"
+
+      # WD7 — the REFERENCE corpus is wider than the ANALYSIS corpus. `.rake` files sit inside `paths:` and
+      # reference project constants, but `PathExpansion::RUBY_GLOB` never reads them, which made them pure
+      # artifacts on two of three corpus targets. Harvesting references from a file is far cheaper than
+      # type-checking it, so the report takes the wider set.
+      REFERENCE_GLOB = "**/*.{rb,rake}"
+
+      # Templates and data files that carry class names as strings. A name here is NOT counted as a reference —
+      # a YAML value is far weaker evidence than a constant node, and treating it as proof would silently hide
+      # real dead code. It demotes the declaration to `cannot-decide` instead, with the file named, so the
+      # reader judges it (ADR-102 WD4).
+      TEMPLATE_GLOB = "**/*.{erb,haml,slim,yml,yaml,json}"
+
+      def run
+        options = parse_options
+        return CLI::EXIT_USAGE if options == :usage_error
+
+        configuration = Configuration.load(options.fetch(:config))
+        paths = @argv.empty? ? configuration.paths : @argv
+        declarations, references, dynamic_uses = scan(paths, configuration)
+        references.concat(signature_references(configuration))
+        dynamic_uses.concat(template_mentions(declarations))
+
+        contribution = Analysis::Reachability::PluginRoots.collect(configuration: configuration)
+        references.concat(plugin_references(contribution.references))
+        graph = Analysis::Reachability::Graph.new(
+          declarations: declarations, references: references, dynamic_uses: dynamic_uses,
+          root_fqns: root_fqns(declarations, options.fetch(:entry_points)) + contribution.roots,
+          foreign: foreign_predicate(configuration)
+        )
+        emit(graph.report, options, supply: root_supply(contribution.roots, declarations))
+        0
+      end
+
+      private
+
+      def parse_options
+        options = { config: nil, format: "text", entry_points: [], limit: nil }
+        parser = OptionParser.new do |opts|
+          opts.banner = USAGE
+          Options.add_config(opts, options)
+          opts.on("--format=FORMAT", "Output format: text (default) or json") { |v| options[:format] = v }
+          opts.on("--entry-point=GLOB", "Treat declarations in files matching GLOB as roots (repeatable)") do |v|
+            options[:entry_points] << v
+          end
+          opts.on("--limit=N", Integer, "Print at most N candidates (default: all)") { |v| options[:limit] = v }
+          # WD5 — refuse rather than silently absorb. A reachability answer is sound only over a full run, and a
+          # user who asked for the fast path must not silently get the slow one.
+          opts.on("--incremental", "(unsupported)") { options[:incremental] = true }
+        end
+        parser.parse!(@argv)
+        return usage_error(parser) if options[:incremental]
+
+        options
+      rescue OptionParser::ParseError => e
+        @err.puts(e.message)
+        :usage_error
+      end
+
+      def usage_error(_parser)
+        @err.puts("rigor unused does not support --incremental: reachability is only sound over a whole-project " \
+                  "run, so an incremental pass would report constants as unused merely because the files that " \
+                  "reference them were served from cache. Re-run without --incremental.")
+        :usage_error
+      end
+
+      # Declarations come from the analysed paths; references additionally from the wider corpus (WD7).
+      def scan(paths, configuration)
+        declaration_files = Analysis::PathExpansion.ruby_files(paths, configuration.exclude_patterns).to_set
+        declarations = []
+        references = []
+        dynamic_uses = []
+        (declaration_files + reference_files(paths, configuration)).sort.each do |file|
+          result = read_and_scan(file, configuration)
+          next if result.nil?
+
+          declarations.concat(result.declarations) if declaration_files.include?(file)
+          references.concat(result.references)
+          dynamic_uses.concat(result.dynamic_uses)
+        end
+        [declarations, references, dynamic_uses]
+      end
+
+      # The reference corpus is the PROJECT, not the analysed paths. A constant declared in `lib/` is commonly
+      # referenced from `config/initializers`, a `.rake` task, or a spec — none of which are in `paths:` — and
+      # treating those as absent is what manufactured artifacts on two of three corpus targets in #345.
+      # Widening the *declaration* set the same way would cancel the gain (measured: +1 / −3 / +2 candidates,
+      # ADR-102 WD2), which is exactly why the two corpora are separated rather than both widened.
+      def reference_files(_paths, configuration)
+        relative = Analysis::Reachability::ProjectFiles.own(Dir.glob(REFERENCE_GLOB, base: Dir.pwd), Dir.pwd)
+        absolute = relative.map { |rel| File.expand_path(rel) }
+        Analysis::PathExpansion.reject_excluded(absolute, configuration.exclude_patterns).to_set
+      end
+
+      def read_and_scan(file, configuration)
+        Analysis::Reachability::Scan.call(path: file, source: File.read(file),
+                                          target_ruby: configuration.target_ruby)
+      rescue SystemCallError
+        nil
+      end
+
+      # A glob is matched against the declaration's path AND its path relative to the working directory:
+      # `configuration.paths` are expanded to absolute, so a user-written `--entry-point=lib/entry.rb` would
+      # otherwise never match anything and silently produce a root set of zero.
+      # A constant named only from the project's own `sig/` is referenced — the #345 probe reported exactly this
+      # as a false candidate until an RBS-side hook was added, because `Reflection.resolve_constant_type` is
+      # source-side only. A signature also DECLARES, though, and {Analysis::Reachability::SignatureScan} is
+      # what keeps the two apart (issue #363).
+      def signature_references(configuration)
+        Array(configuration.signature_paths).flat_map do |dir|
+          next [] unless File.directory?(dir)
+
+          Dir.glob(File.join(dir, "**/*.rbs")).flat_map { |file| Analysis::Reachability::SignatureScan.call(file) }
+        end
+      end
+
+      # #350 — a plugin's `:reachability_references` fact enters the graph exactly where a scanned file-level
+      # reference does: `from: nil` (so it seeds) carrying the role the plugin claimed. That is what keeps a
+      # class named only by a FactoryBot `class:` string in the `reachable only from tests` section instead of
+      # promoting it to production-reachable, which rooting it would have done silently.
+      #
+      # `path` is a synthetic marker rather than a file: the graph never reads a reference's path (rows are
+      # located from the DECLARATION site), and inventing a plausible-looking file path for a fact would be a
+      # worse lie than an obviously synthetic one.
+      def plugin_references(rows)
+        rows.map do |reference|
+          Analysis::Reachability::Scan::Reference.new(as_written: reference.name, nesting: [].freeze, from: nil,
+                                                      role: reference.role, path: "(plugin)", line: 1)
+        end
+      end
+
+      def template_mentions(declarations)
+        names = declarations.map(&:fqn)
+        return [] if names.empty?
+
+        Analysis::Reachability::ProjectFiles.own(Dir.glob(TEMPLATE_GLOB, base: Dir.pwd), Dir.pwd).flat_map do |rel|
+          text = File.read(File.expand_path(rel)).scrub
+          names.filter_map do |fqn|
+            next unless text.include?(fqn)
+
+            Analysis::Reachability::Scan::DynamicUse.new(name: nil, prefix: fqn, site: nil,
+                                                         reason: "named as a string in #{rel}",
+                                                         path: rel, line: 1)
+          end
+        rescue SystemCallError, ArgumentError
+          []
+        end
+      end
+
+      def root_fqns(declarations, globs)
+        return [] if globs.empty?
+
+        matcher = Analysis::Reachability::ProjectFiles.method(:entry_point_match?)
+        cwd = "#{File.expand_path(Dir.pwd)}/"
+        declarations.filter_map do |d|
+          relative = d.path.delete_prefix(cwd)
+          d.fqn if globs.any? { |g| matcher.call(g, d.path) || matcher.call(g, relative) }
+        end
+      end
+
+      # WD6 — ownership means "declared FIRST here". Reopening a gem or stdlib class registers it as a project
+      # declaration, which produced three of redmine's artifacts from a single initializer. A name the bundled
+      # (non-project) environment already knows is not ours to call unused. The project's own `sig/` is
+      # deliberately excluded from this environment, so a project class that ships a signature stays owned.
+      def foreign_predicate(configuration)
+        env = Environment.for_project(libraries: configuration.libraries, signature_paths: [])
+        ->(fqn) { !env.singleton_for_name(fqn).nil? }
+      rescue StandardError
+        ->(_fqn) { false }
+      end
+
+      # ADR-102 § Consequences — "a root source that OVER-supplies silently hides real dead code, which is
+      # worse than one that under-supplies, so each plugin's contribution needs its own corpus check". A
+      # supplied root naming a constant the project does not declare is inert in the graph, but it is the
+      # observable symptom of a root source drifting away from the code — a renamed controller, an
+      # inflection the plugin gets wrong, a convention that stopped holding. Reporting the count makes that
+      # drift measurable on a real project instead of invisible.
+      Supply = Data.define(:supplied, :unmatched)
+      private_constant :Supply
+
+      def root_supply(plugin_roots, declarations)
+        declared = declarations.to_set(&:fqn)
+        Supply.new(supplied: plugin_roots.size, unmatched: plugin_roots.count { |fqn| !declared.include?(fqn) })
+      end
+
+      def emit(report, options, supply:)
+        @out.puts(options.fetch(:format) == "json" ? json(report, options, supply) : text(report, options, supply))
+      end
+
+      def json(report, options, supply)
+        JSON.pretty_generate(
+          declared: report.declared, reachable: report.reachable, roots: report.roots, edges: report.edges,
+          namespaces: report.namespaces,
+          plugin_roots: supply.supplied, plugin_roots_unmatched: supply.unmatched,
+          candidates: rows_json(report.candidates, options), test_only: rows_json(report.test_only, options),
+          undecidable: limited(report.undecidable, options).map do |u|
+            { name: u.fqn, path: u.path, line: u.line, reason: u.reason }
+          end
+        )
+      end
+
+      def rows_json(rows, options)
+        limited(rows, options).map { |c| { name: c.fqn, path: c.path, line: c.line } }
+      end
+
+      def text(report, options, supply)
+        lines = ["Reachability", "  declared (project-owned): #{report.declared}",
+                 "  roots:                    #{report.roots}#{plugin_root_note(supply)}",
+                 "  reachable:                #{report.reachable}",
+                 "  candidates:               #{report.candidates.size}",
+                 "  reachable only from tests: #{report.test_only.size}",
+                 "  cannot decide:            #{report.undecidable.size}",
+                 "  namespace-only (excluded):  #{report.namespaces}"]
+        lines.concat(section("Candidates — nothing reachable references these", report.candidates, options))
+        lines.concat(section("Reachable only from test code — live test, dead production path",
+                             report.test_only, options))
+        lines.concat(undecidable_section(report.undecidable, options))
+        lines << ""
+        lines << "These are CANDIDATES, not findings. The measured precision of this report on an adjudicated"
+        lines << "corpus target is 7% — every row needs a human to confirm it. Roots a framework supplies come"
+        lines << "from the project's plugins, so a framework Rigor has no plugin for still reads as an upper bound."
+        lines.join("\n")
+      end
+
+      # `(N from plugins, M matched nothing)` — omitted entirely when no plugin contributed, so a
+      # non-Rails project's report is unchanged. A non-zero `matched nothing` is the over-supply signal
+      # described on {#root_supply}: those roots claim constants this project does not declare.
+      def plugin_root_note(supply)
+        return "" if supply.supplied.zero?
+
+        " (#{supply.supplied} from plugins, #{supply.unmatched} matched no declaration)"
+      end
+
+      def undecidable_section(rows, options)
+        return [] if rows.empty?
+
+        out = ["", "Cannot decide — something can name these at runtime (#{rows.size})"]
+        limited(rows, options).each_with_index do |u, i|
+          out << format("  %<n>3d  %<name>-52s %<path>s:%<line>d", n: i + 1, name: u.fqn, path: u.path,
+                                                                   line: u.line)
+          out << "       #{u.reason}"
+        end
+        out
+      end
+
+      def section(title, rows, options)
+        return [] if rows.empty?
+
+        out = ["", "#{title} (#{rows.size})"]
+        limited(rows, options).each_with_index do |c, i|
+          out << format("  %<n>3d  %<name>-52s %<path>s:%<line>d", n: i + 1, name: c.fqn, path: c.path, line: c.line)
+        end
+        out
+      end
+
+      def limited(candidates, options)
+        limit = options.fetch(:limit)
+        limit ? candidates.first(limit) : candidates
+      end
+    end
+  end
+end

data/lib/rigor/cli.rb

@@ -37,6 +37,7 @@ module Rigor
       "type-of" => :run_type_of,
       "trace" => :run_trace,
       "type-scan" => :run_type_scan,
+      "effects" => :run_effects,
       "explain" => :run_explain,
       "diff" => :run_diff,
       "sig-gen" => :run_sig_gen,
@@ -44,6 +45,7 @@ module Rigor
       "mcp" => :run_mcp,
       "baseline" => :run_baseline,
       "triage" => :run_triage,
+      "unused" => :run_unused,
       "coverage" => :run_coverage,
       "plugins" => :run_plugins,
       "plugin" => :run_plugin,
@@ -220,6 +222,12 @@ module Rigor
       TypeScanCommand.new(argv: @argv, out: @out, err: @err).run
     end
 
+    def run_effects
+      require_relative "cli/effects_command"
+
+      EffectsCommand.new(argv: @argv, out: @out, err: @err).run
+    end
+
     def run_explain
       require_relative "cli/explain_command"
 
@@ -262,6 +270,12 @@ module Rigor
       CLI::TriageCommand.new(argv: @argv, out: @out, err: @err).run
     end
 
+    def run_unused
+      require_relative "cli/unused_command"
+
+      CLI::UnusedCommand.new(argv: @argv, out: @out, err: @err).run
+    end
+
     def run_coverage
       require_relative "cli/coverage_command"
 
@@ -341,6 +355,8 @@ module Rigor
           type-of    Print the inferred type at FILE:LINE:COL
           trace      Replay how the engine typed FILE as a terminal animation
           type-scan  Report Scope#type_of coverage across PATHs
+          effects    Report each method's effect labels, and the committed effect snapshot
+                     (ADR-103, opt-in; effects update/check/diff/explain)
           explain    Print the description of one or all CheckRules
           diff       Compare current diagnostics to a saved baseline JSON
           sig-gen    Emit RBS skeletons inferred from .rb sources (ADR-14)

data/lib/rigor/configuration/severity_profile.rb

@@ -63,6 +63,19 @@ module Rigor
           # ADR-100 — a new required diagnostic (ADR-50 WD1), so it is `:off` in every shipped profile and
           # reaches a user only through the `use-of-void-value` bleeding-edge feature, which overrides this
           # to `:warning`.
+          # ADR-103 WD8 / #383 — opt-in twice over (the `effects:` block, then the author's own
+          # envelope directive), so it is never unsolicited noise and needs no bleeding-edge gate:
+          # `:warning` even under lenient, `:error` under strict.
+          "effect.envelope-exceeded" => :warning,
+          # ADR-103 WD14 / #386 — the inherited-bound reading rides its sibling's severities exactly:
+          # both-sides-authored (someone wrote the ancestor's envelope), and as strict as proven.
+          "effect.liskov-widened" => :warning,
+          # ADR-103 WD14 — `unknown-label` info / info / warning. It reports that a bound stopped
+          # bounding, never that code is wrong, so even `strict` stops at `:warning`.
+          "effect.unknown-label" => :info,
+          # The residual is advisory in every profile: it says a declaration is inert, and the fix is
+          # a config edit the author may deliberately not want.
+          "effect.annotations-unchecked" => :info,
           "static.value-use.void" => :off,
           # Opt-in author assertion: you only see it if you wrote a
           # `conforms-to` directive, so it stays a :warning even in
@@ -101,6 +114,10 @@ module Rigor
           "suppression.empty" => :warning,
           "suppression.unknown-marker" => :warning,
           "static.value-use.void" => :off,
+          "effect.envelope-exceeded" => :warning,
+          "effect.liskov-widened" => :warning,
+          "effect.unknown-label" => :info,
+          "effect.annotations-unchecked" => :info,
           "rbs_extended.unsatisfied-conformance" => :warning
         }.freeze,
         strict: {
@@ -135,6 +152,12 @@ module Rigor
           "suppression.unknown-marker" => :warning,
           # `:off` even under strict: the gate is `bleeding_edge:`, not the profile (ADR-50 WD1 / ADR-100).
           "static.value-use.void" => :off,
+          "effect.envelope-exceeded" => :error,
+          "effect.liskov-widened" => :error,
+          "effect.unknown-label" => :warning,
+          # `:info` even under strict: a residual that failed a build would punish the project for
+          # carrying an annotation it has not opted into checking, which is the opposite of the point.
+          "effect.annotations-unchecked" => :info,
           "rbs_extended.unsatisfied-conformance" => :error
         }.freeze
       }.freeze