rigortype 0.3.3 → 0.3.5

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,
@@ -82,6 +84,17 @@ module Rigor
     rescue OptionParser::ParseError => e
       @err.puts(e.message)
       EXIT_USAGE
+    rescue ConfigurationError => e
+      # #433 — a mistake in `.rigor.yml` is the same kind of event as a bad flag, and belongs in the same
+      # shape: one `rigor:` line naming the key, and the conventional usage exit code. It used to escape
+      # as an uncaught exception with a ~30-frame backtrace naming a file inside `lib/rigor/`, which reads
+      # as a crash even though the message it carried said exactly which key to fix.
+      #
+      # Caught here rather than per command because every command loads a configuration, and the ones
+      # that resolve a key later (`effects update` expanding `snapshot.reach:` once the plugins that
+      # register presets have loaded) would each need their own rescue at their own point.
+      @err.puts("rigor: #{e.message}")
+      EXIT_USAGE
     end
 
     private
@@ -158,7 +171,7 @@ module Rigor
         # - paths:       directories scanned by `rigor check` and
         #                `rigor type-scan` when no path is given.
         # - plugins:     opt-in list of plugin gem names to load.
-        #                See https://github.com/rigortype/rigor/tree/main/plugins
+        #                See https://github.com/rigortype/rigor/tree/master/plugins
         #                for production plugins (rigor-activerecord, rigor-sorbet, …).
         # - disable:     list of `rigor check` rule identifiers to
         #                silence project-wide. The shipped rules are
@@ -220,6 +233,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 +281,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 +366,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