ruby_ability_graph 0.1.0

data/README.md

@@ -0,0 +1,139 @@
+# ruby_ability_graph
+
+Loads a Rails app's [CanCanCan](https://github.com/CanCanCommunity/cancancan) `Ability` class in isolation and reports raw `can?`/`cannot?` results across every role x action x model combination -- so you can see who can access what without booting the full app or hand-tracing every conditional.
+
+**Status:** Each result is classified `resolved` (structured condition captured) or `unsupported` (declared but not analyzed, with a reason and source pointer). `scan` prints a human-readable table by default, a versioned JSON schema on request, can diff results against a simple policy file, and can render an interactive HTML graph of the whole thing.
+
+## Installation
+
+Not on RubyGems yet -- point Bundler at the repo instead:
+
+```ruby
+gem "ruby_ability_graph", github: "m1gd0n-dev/ruby-ability-graph"
+```
+
+Requires Ruby >= 4.0 and a C compiler to install -- `prism` compiles a native extension at install time. The Rails app you're scanning doesn't need to be on Ruby 4, though -- point `--ruby-bin` at whatever Ruby that app runs on and the analysis subprocess uses that instead.
+
+## Usage
+
+### 1. Find out what your Ability class needs
+
+`inspect` statically scans `Ability#initialize` (via [Prism](https://github.com/ruby/prism), without executing your app) and lists every method it calls on `user`:
+
+```
+ruby-ability-graph inspect APP_PATH [--ability-file FILE] [--ability-class NAME]
+```
+
+```
+Methods called on `user` in Ability#initialize:
+  admin?
+  id
+
+Your roles file needs a value for each, per role that reaches it.
+```
+
+### 2. Write a roles file
+
+Create `.ability_graph_roles.yml` at your app root, mapping each role you want scanned to stand-in values for the methods `inspect` found:
+
+```yaml
+admin:
+  admin?: true
+member:
+  admin?: false
+  id: 42
+```
+
+### 3. Scan
+
+```
+ruby-ability-graph scan APP_PATH [--roles-file FILE] [--ability-file FILE] [--ability-class NAME]
+                                  [--require FILE]... | [--rails-boot [--rails-env ENV]]
+                                  [--ruby-bin PATH] [--format table|json] [--policy-file FILE]
+                                  [--html-report FILE]
+```
+
+This loads your `Ability` class in a subprocess and runs `can?` for every role x action x model combination it finds.
+
+By default it prints a human-readable table plus a resolved/unsupported coverage line:
+
+```
+ROLE    ACTION  MODEL     ALLOWED  CONFIDENCE   CONDITION
+admin   read    Document  true     resolved     -
+member  read    Document  true     resolved     {"team_id" => 7}
+member  update  Document  true     unsupported  -
+
+2/3 resolved (66.7%)
+```
+
+Pass `--format json` for the same data as structured, versioned JSON instead:
+
+```json
+{
+  "schema_version": 1,
+  "results": [
+    { "role": "admin", "action": "read", "model": "Document", "allowed": true,
+      "confidence": "resolved", "condition": null, "reasons": [], "sources": [] },
+    { "role": "member", "action": "read", "model": "Document", "allowed": true,
+      "confidence": "resolved", "condition": { "team_id": 7 }, "reasons": [], "sources": [] },
+    { "role": "member", "action": "update", "model": "Document", "allowed": true,
+      "confidence": "unsupported", "condition": null, "reasons": ["block_condition"],
+      "sources": [{ "file": "app/models/ability.rb", "line": 12, "text": "can :update, Document do |doc| ... end" }] }
+  ]
+}
+```
+
+**Options:**
+
+| Flag | Default | Purpose |
+|---|---|---|
+| `--roles-file FILE` | `APP_PATH/.ability_graph_roles.yml` | YAML file from step 2 |
+| `--ability-file FILE` | `app/models/ability.rb` | Path to the `Ability` class, relative to `APP_PATH` |
+| `--ability-class NAME` | `Ability` | Constant name to load, e.g. `Spree::Ability` for a namespaced/engine-provided one |
+| `--require FILE` (repeatable) | -- | Preload a file your `Ability` class references but doesn't require itself. Not compatible with `--rails-boot` |
+| `--rails-boot [--rails-env ENV]` | off / `test` | Boot via the target's own `bin/rails runner` so real Zeitwerk autoloading resolves everything -- no manual `--require` list needed. Not compatible with `--require` |
+| `--ruby-bin PATH` | `ruby` (via `PATH`) | Ruby executable for the analysis subprocess, if the target app needs a different Ruby version than this gem runs under |
+| `--format table\|json` | `table` | `table` for a terminal-friendly summary, `json` for the versioned schema above |
+| `--policy-file FILE` | -- | Run a policy check against the results (see below); path is relative to `APP_PATH` |
+| `--html-report FILE` | -- | Write an interactive HTML graph of the results (see below) to this path, relative to `APP_PATH` |
+
+Note: `--rails-boot` runs the target's *entire* boot sequence, not just the `Ability` class -- if the app needs a JS runtime, a live DB connection, or anything else at boot time (not merely at asset-compile time), that has to already be satisfied in whatever environment you're running the scan from. This is most likely to bite in a stripped-down CI container or sandbox rather than a normal dev machine. If the target's full boot is heavy or fragile, `--require`ing just what the `Ability` class needs is usually simpler than fighting its boot process.
+
+### 4. Policy checks (optional)
+
+Declare who's *supposed* to be able to do what, and let `scan` flag any role that can actually do more. The policy language is deliberately flat -- `model` + `action` + `allowed_roles`, no nested logic:
+
+```yaml
+# policy.yml
+policies:
+  - model: Payment
+    action: read
+    allowed_roles: [admin]
+  - model: Document
+    action: destroy
+    allowed_roles: [admin, owner]
+```
+
+```
+ruby-ability-graph scan APP_PATH --policy-file policy.yml
+```
+
+A violation is any `(role, action, model)` combination the scan found `allowed: true` for, where `role` isn't in that policy's `allowed_roles`. Violations are appended to the table (or the `"policy_violations"` key in JSON output), and `scan` exits `1` if any are found -- so this doubles as a CI gate. A clean policy check exits `0`.
+
+Note: a policy check is only as trustworthy as the underlying result's `confidence`. A violation on an `unsupported` result means the role stand-in used for this run happened to be allowed -- it isn't a guarantee about every user with that role, since the condition itself wasn't fully analyzed. Treat those as "investigate," not "confirmed."
+
+### 5. HTML report (optional)
+
+```
+ruby-ability-graph scan APP_PATH --html-report report.html
+```
+
+Writes a single, self-contained HTML file -- inlined CSS/JS, no server, no CDN assets, nothing fetched over the network -- showing an interactive role → action → resource graph. Hover a role to trace everything it can reach; hover an edge for the underlying condition and confidence. Edges are solid green where `resolved`, dashed amber where `unsupported`, and solid red where a `--policy-file` check (if given) found a violation. A coverage line at the top mirrors the table's resolved/total summary. Only `allowed: true` results become edges -- it's a "who can access what" diagram, not a dump of every denial.
+
+Combine it with `--policy-file` to get violations highlighted directly on the graph, not just listed in the table/JSON output. The file opens straight from disk (`file://`) in any browser -- no need to serve it.
+
+## Security
+
+`scan` executes code in `APP_PATH` -- it loads your `Ability` class (and anything that file requires) in a subprocess. Only run it against apps you trust. `inspect` is static analysis only (via Prism) and never executes the target.
+
+`--html-report` makes no network requests, ever -- everything it needs is inlined into the one file it writes. It does embed your role names, action names, model names, and raw condition values into that file, though, so treat the generated report itself with the same care as the scan results: don't publish it somewhere untrusted people can read it if that data is sensitive.

data/exe/ruby-ability-graph

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "ruby_ability_graph"
+
+RubyAbilityGraph::CLI.start(ARGV)

data/lib/ruby_ability_graph/cli.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "yaml"
+require "json"
+
+module RubyAbilityGraph
+  # Command-line entry point: `scan` runs the role x action x model analysis
+  # via Harness, `inspect` runs the roles-file authoring aid via Inspector.
+  class CLI
+    USAGE = <<~USAGE.chomp
+      Usage: ruby-ability-graph scan APP_PATH [--roles-file FILE] [--ability-file FILE]
+                                               [--ability-class NAME]
+                                               [--require FILE]... | [--rails-boot [--rails-env ENV]]
+                                               [--ruby-bin PATH] [--format table|json] [--policy-file FILE]
+                                               [--html-report FILE]
+             ruby-ability-graph inspect APP_PATH [--ability-file FILE] [--ability-class NAME]
+    USAGE
+
+    def self.start(argv)
+      new.run(argv)
+    end
+
+    def run(argv)
+      command, *rest = argv
+      case command
+      when "scan" then scan(rest)
+      when "inspect" then inspect_ability(rest)
+      else warn USAGE and exit(1)
+      end
+    rescue OptionParser::ParseError => e
+      abort(e.message)
+    end
+
+    private
+
+    def scan(argv)
+      options, app_path = RubyAbilityGraph::ScanOptions.parse(argv)
+      roles = load_roles(options[:roles_file], app_path)
+      results = RubyAbilityGraph::Harness.new(**harness_kwargs(options, app_path, roles)).run
+      policy_report = load_policy_report(options[:policy_file], app_path, results)
+      output_results(options, app_path, results, policy_report)
+    end
+
+    def output_results(options, app_path, results, policy_report)
+      write_html_report(options[:html_report], app_path, results, policy_report)
+
+      presenter = RubyAbilityGraph::ScanPresenter.new(
+        format: options[:format], results: results, policy_report: policy_report
+      )
+      puts presenter.render
+      exit(1) if presenter.problems?
+    end
+
+    # rails_env/ruby_bin are only included when set at all, so Harness's own
+    # keyword defaults apply otherwise -- an explicit nil would override
+    # them instead. #compact drops both when absent (rails_boot: false is a
+    # real value, not "absent", so it survives).
+    def harness_kwargs(options, app_path, roles)
+      {
+        app_path: app_path, roles: roles, ability_file: options[:ability_file],
+        ability_class_name: options[:ability_class], requires: options[:requires],
+        rails_boot: options[:rails_boot], rails_env: options[:rails_env], ruby_bin: options[:ruby_bin]
+      }.compact
+    end
+
+    # nil (not merely empty) means "no --policy-file given" -- ScanPresenter
+    # uses that distinction to decide whether to print a policy section at all.
+    def load_policy_report(policy_file, app_path, results)
+      return nil unless policy_file
+
+      path = File.expand_path(policy_file, app_path)
+      abort("No policy file found at #{path}.") unless File.exist?(path)
+
+      RubyAbilityGraph::PolicyChecker.call(policies: parse_policy_file(path), results: results)
+    end
+
+    def parse_policy_file(path)
+      data = YAML.safe_load_file(path)
+      abort("Policy file #{path} must be a YAML mapping with a top-level `policies:` list.") unless data.is_a?(Hash)
+
+      data["policies"] || []
+    rescue Psych::SyntaxError => e
+      abort("Failed to parse policy file #{path}: #{e.message}")
+    end
+
+    # Written to stderr, not stdout -- keeps `--format json` pipeable without
+    # this confirmation line landing in the middle of the JSON payload.
+    def write_html_report(html_report, app_path, results, policy_report)
+      return unless html_report
+
+      path = File.expand_path(html_report, app_path)
+      violations = policy_report&.violations
+      File.write(path, RubyAbilityGraph::HtmlReport.call(results: results, violations: violations))
+      warn "HTML report written to #{path}"
+    end
+
+    def inspect_ability(argv)
+      app_path, options = parse_inspect_args(argv)
+      inspector = build_inspector(options, app_path)
+      result = run_inspector(inspector)
+      print_inspection_result(result, options[:ability_class])
+    end
+
+    def build_inspector(options, app_path)
+      RubyAbilityGraph::Inspector.new(
+        ability_file: File.expand_path(options[:ability_file], app_path),
+        ability_class_name: options[:ability_class]
+      )
+    end
+
+    def run_inspector(inspector)
+      inspector.call
+    rescue RubyAbilityGraph::Inspector::InspectionError => e
+      abort(e.message)
+    end
+
+    def parse_inspect_args(argv)
+      options = { ability_file: RubyAbilityGraph::Harness::DEFAULT_ABILITY_FILE, ability_class: "Ability" }
+      build_inspect_parser(options).parse!(argv)
+
+      app_path = argv.shift
+      abort(USAGE) unless app_path
+      [app_path, options]
+    end
+
+    ABILITY_CLASS_HELP = "The class name exactly as written at its `class` statement in that file -- " \
+                         "usually just Ability even when it's namespaced (e.g. `module Spree; class " \
+                         "Ability`), unless it's written inline as `class Spree::Ability` (default: Ability)"
+    private_constant :ABILITY_CLASS_HELP
+
+    def build_inspect_parser(options)
+      OptionParser.new do |opts|
+        opts.on("--ability-file FILE", "Path to the Ability class file, relative to APP_PATH") do |v|
+          options[:ability_file] = v
+        end
+        opts.on("--ability-class NAME", ABILITY_CLASS_HELP) { |v| options[:ability_class] = v }
+      end
+    end
+
+    def print_inspection_result(result, ability_class)
+      puts "Methods called on `user` in #{ability_class}#initialize:"
+      result.method_names.each { |m| puts "  #{m}" }
+      puts
+      puts "Your roles file needs a value for each, per role that reaches it."
+      puts
+      puts "Warning: #{result.warning}" if result.warning
+    end
+
+    def load_roles(roles_file, app_path)
+      path = roles_file || File.join(app_path, ".ability_graph_roles.yml")
+      unless File.exist?(path)
+        abort("No roles file found at #{path}. Pass --roles-file or add .ability_graph_roles.yml to the app root.")
+      end
+      YAML.safe_load_file(path, permitted_classes: [Symbol]).transform_values do |attrs|
+        (attrs || {}).to_h { |k, v| [k.to_s.to_sym, v] }
+      end
+    end
+  end
+end

data/lib/ruby_ability_graph/enumerator.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+require_relative "rule_classifier"
+
+module RubyAbilityGraph
+  # Runs a loaded Ability class's can? checks across every role x declared
+  # action x declared model combination, classifying each result as
+  # resolved/unsupported (via RuleClassifier) rather than returning a bare
+  # boolean.
+  class Enumerator
+    Result = Struct.new(
+      :role, :action, :model, :allowed, :confidence, :condition, :reasons, :sources, keyword_init: true
+    )
+    DEFAULT_ACTIONS = %i[index show create update destroy manage read].freeze
+
+    # Records where each rule was truly declared, by wrapping CanCan::Ability's
+    # own rule-append point -- prepended onto the CanCan::Ability MODULE
+    # itself (not a specific Ability class), so it applies uniformly to every
+    # class that includes it. That matters because larger apps commonly split
+    # authorization across several classes merged together (e.g. a top-level
+    # `Ability` doing `merge Abilities::Administrator.new(user)`, itself
+    # merging further sub-abilities -- found dogfooding consuldemocracy).
+    # Prepending only the top-level class would mean a rule declared inside
+    # a merged-in class gets *re-added* during merge, and naive recording
+    # would attribute it to the merge call site, not its real declaration --
+    # every rule sharing that merge line would then look like it fired more
+    # than once, indistinguishable from a genuine loop-built rule.
+    #
+    # The source is stashed directly on the rule object (set once, at first
+    # sighting) rather than in an array indexed by position, so it survives
+    # being re-added to another ability's own @rules during merge.
+    module RuleSourceRecording
+      # Larger apps commonly split `can`/`cannot` declarations out of Ability
+      # itself via a plain forwarding method -- Solidus's whole
+      # PermissionSets framework works this way (`delegate :can, :cannot,
+      # :user, to: :ability` in every permission set's base class, found
+      # dogfooding solidus). A delegate-generated method's OWN recorded
+      # file/line is wherever `delegate :can, ...` itself was written, not
+      # the permission set subclass that actually calls it -- so the first
+      # non-cancancan frame there is a dead end, and every rule declared
+      # through that same delegate line collapses to one identical,
+      # unhelpful source pointer. Skipping frames whose method name is
+      # itself can/cannot (regardless of whether the forwarding was done via
+      # `delegate`, `alias`, or a hand-written wrapper) walks past that and
+      # lands on the real call site instead.
+      #
+      # Location#label isn't just the bare method name -- on this Ruby
+      # version it's qualified as "PermBase#can" (confirmed empirically;
+      # comparing against a bare "can"/"cannot" silently never matched and
+      # let the very bug this is meant to fix through). Match on either form.
+      FORWARDING_METHOD_NAME = /(\A|#)(can|cannot)\z/
+
+      def add_rule(rule)
+        unless rule.instance_variable_defined?(:@rag_source)
+          location = caller_locations.find do |loc|
+            !loc.path.include?("cancancan") && !FORWARDING_METHOD_NAME.match?(loc.label)
+          end
+          rule.instance_variable_set(:@rag_source, location)
+        end
+        super
+      end
+    end
+    private_constant :RuleSourceRecording
+
+    def self.call(ability_class:, role_stand_ins:)
+      new(ability_class: ability_class, role_stand_ins: role_stand_ins).call
+    end
+
+    def initialize(ability_class:, role_stand_ins:)
+      @ability_class = ability_class
+      @role_stand_ins = role_stand_ins
+    end
+
+    def call
+      ensure_source_recording!
+      abilities = @role_stand_ins.transform_values { |user| @ability_class.new(user) }
+      models = declared_models(abilities.values)
+      actions = declared_actions(abilities.values)
+
+      build_results(abilities, models, actions)
+    end
+
+    private
+
+    # Prepended onto the CanCan::Ability module -- see RuleSourceRecording --
+    # so this only ever needs to run once, regardless of which Ability-like
+    # class we're pointed at. No-op entirely if the target's cancancan
+    # version doesn't define #add_rule -- source/dynamic-generation data is
+    # simply unavailable then, not fatal.
+    def ensure_source_recording!
+      return if CanCan::Ability.ancestors.include?(RuleSourceRecording)
+      return unless CanCan::Ability.method_defined?(:add_rule) || CanCan::Ability.private_method_defined?(:add_rule)
+
+      CanCan::Ability.prepend(RuleSourceRecording)
+    end
+
+    def build_results(abilities, models, actions)
+      results = []
+      abilities.each do |role, ability|
+        dynamic_rules = dynamic_rule_set(ability.send(:rules))
+        models.each do |model|
+          actions.each { |action| results << build_result(role, ability, model, action, dynamic_rules) }
+        end
+      end
+      results
+    end
+
+    # A rule counts as dynamically generated only if it shares its true
+    # declaration line with at least one OTHER rule from this same
+    # instantiation whose subjects/actions/conditions actually differ -- e.g.
+    # Fat Free CRM's `permissions.each { |p| can :manage, ..., id: p.asset_id }`,
+    # where every iteration produces a different condition. Same line but
+    # every rule otherwise identical is what a merged-in class reached via
+    # more than one path looks like (see RuleSourceRecording) -- that's
+    # static duplication, not a loop, and shouldn't taint an otherwise
+    # perfectly resolvable rule.
+    def dynamic_rule_set(rules)
+      rules.group_by { |rule| location_key(rule_source(rule)) }
+           .reject { |key, _| key.nil? }
+           .values
+           .select { |group| group.size > 1 && varies?(group) }
+           .flatten
+           .to_set
+    end
+
+    # Thread::Backtrace::Location has no value equality of its own -- two
+    # separate calls to caller_locations, even for the exact same physical
+    # line, return objects that are neither `==` nor `eql?` to each other
+    # (confirmed empirically). Grouping by the raw Location silently never
+    # merged anything, so this whole dynamic-vs-static check was a no-op
+    # from the moment it shipped. [path, lineno] is a plain, hashable-by-
+    # value key that actually collapses same-site rules.
+    def location_key(location)
+      return nil unless location
+
+      [location.path, location.lineno]
+    end
+
+    def varies?(group)
+      group.map { |rule| [rule.subjects, rule.actions, rule.conditions] }.uniq.size > 1
+    end
+
+    def build_result(role, ability, model, action, dynamic_rules)
+      contributing = relevant_rules(ability, action, model)
+      classifications = contributing.map { |rule| classify(rule, model, dynamic_rules) }
+
+      Result.new(
+        role: role.to_s,
+        action: action.to_s,
+        model: model_name(model),
+        allowed: ability.can?(action, model),
+        **verdict(classifications)
+      )
+    end
+
+    def classify(rule, model, dynamic_rules)
+      return dynamic_classification(rule) if dynamic_rules.include?(rule)
+
+      classification = RuleClassifier.call(rule: rule, model: model)
+      classification.source = source_snippet(rule_source(rule)) if classification.confidence == "unsupported"
+      classification
+    end
+
+    def dynamic_classification(rule)
+      RuleClassifier::Classification.new(
+        confidence: "unsupported",
+        condition: nil,
+        reason: "dynamic_rule_generation",
+        source: source_snippet(rule_source(rule))
+      )
+    end
+
+    # Every rule contributing to this (action, model) pair must itself be
+    # resolved for the combined result to be resolved -- we trust can? for
+    # the boolean, not our own guess at resolution order.
+    def verdict(classifications)
+      unsupported = classifications.reject { |c| c.confidence == "resolved" }
+      return resolved_verdict(classifications) if unsupported.empty?
+
+      {
+        confidence: "unsupported",
+        condition: nil,
+        reasons: unsupported.map(&:reason).uniq,
+        sources: unsupported.map(&:source).compact
+      }
+    end
+
+    def resolved_verdict(classifications)
+      conditions = classifications.filter_map(&:condition)
+      condition = conditions.size <= 1 ? conditions.first : conditions
+      { confidence: "resolved", condition: condition, reasons: [], sources: [] }
+    end
+
+    # Rules whose action/subject match this (action, model) pair, regardless
+    # of whether their condition currently evaluates true or false -- any one
+    # of them being unsupported taints the whole pair (see #verdict).
+    def relevant_rules(ability, action, model)
+      if ability.respond_to?(:relevant_rules, true)
+        ability.send(:relevant_rules, action, model)
+      else
+        ability.send(:rules).select { |r| naive_relevant?(r, action, model) }
+      end
+    end
+
+    # Fallback only, if #relevant_rules isn't available on this cancancan
+    # version -- no alias-expansion awareness beyond :manage.
+    def naive_relevant?(rule, action, model)
+      (rule.subjects.include?(model) || rule.subjects.include?(:all)) &&
+        (rule.actions.include?(action) || rule.actions.include?(:manage))
+    end
+
+    def rule_source(rule)
+      rule.instance_variable_get(:@rag_source) if rule.instance_variable_defined?(:@rag_source)
+    end
+
+    def source_snippet(location)
+      return nil unless location
+
+      { "file" => location.path, "line" => location.lineno, "text" => source_line(location) }
+    end
+
+    def source_line(location)
+      File.readlines(location.path)[location.lineno - 1]&.strip
+    rescue Errno::ENOENT, ArgumentError
+      nil
+    end
+
+    def declared_models(abilities)
+      models = Set.new
+      abilities.each do |ability|
+        ability.send(:rules).each do |rule|
+          rule.subjects.each { |subject| models << subject unless subject == :all }
+        end
+      end
+      models.to_a
+    end
+
+    def declared_actions(abilities)
+      actions = Set.new(DEFAULT_ACTIONS)
+      abilities.each do |ability|
+        ability.send(:rules).each { |rule| rule.actions.each { |action| actions << action } }
+      end
+      actions.to_a
+    end
+
+    def model_name(model)
+      model.respond_to?(:name) ? model.name : model.to_s
+    end
+  end
+end

data/lib/ruby_ability_graph/harness.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require "open3"
+require "tempfile"
+require "json"
+
+module RubyAbilityGraph
+  # Loads a target app's CanCanCan Ability class in a subprocess and reports
+  # raw can?/cannot? results across the role x action x model cross-product.
+  class Harness
+    class LoadError < StandardError; end
+
+    DEFAULT_ABILITY_FILE = "app/models/ability.rb"
+    DEFAULT_RAILS_ENV = "test"
+    MARKER = "RUBY_ABILITY_GRAPH_RESULT:"
+
+    def initialize(app_path:, roles:, ability_file: DEFAULT_ABILITY_FILE, ability_class_name: "Ability", requires: [],
+                   rails_boot: false, rails_env: DEFAULT_RAILS_ENV, ruby_bin: "ruby")
+      validate_requires_compatibility!(rails_boot, requires)
+
+      @app_path = File.expand_path(app_path)
+      @roles = roles
+      @ability_file = ability_file
+      @ability_class_name = ability_class_name
+      @requires = requires
+      @rails_boot = rails_boot
+      @rails_env = rails_env
+      @ruby_bin = ruby_bin
+    end
+
+    def run
+      Tempfile.create(["ruby_ability_graph_runner", ".rb"]) do |file|
+        file.write(runner_script)
+        file.flush
+        stdout, stderr, status = execute(file.path)
+        unless status.success?
+          raise LoadError, "Failed to load and analyze #{@ability_class_name} in #{@app_path}:\n#{stderr}"
+        end
+
+        extract_results(stdout)
+      end
+    end
+
+    private
+
+    def validate_requires_compatibility!(rails_boot, requires)
+      return unless rails_boot && !requires.empty?
+
+      raise ArgumentError, "requires: is not compatible with rails_boot: -- once Zeitwerk is live via " \
+                           "bin/rails runner, referenced classes resolve on their own; a manual requires: " \
+                           "list is superfluous. Drop one or the other."
+    end
+
+    def execute(script_path)
+      return execute_via_rails_runner(script_path) if @rails_boot
+
+      command = bundler_project? ? ["bundle", "exec", @ruby_bin] : [@ruby_bin]
+      # nosemgrep: ruby.lang.security.dangerous-exec.dangerous-exec -- @ruby_bin/@app_path are caller-supplied
+      # tool config, not untrusted remote input; spawning the target app is this harness's intended function.
+      Open3.capture3(*command, script_path, chdir: @app_path)
+    end
+
+    def execute_via_rails_runner(script_path)
+      rails_bin = File.join(@app_path, "bin", "rails")
+      unless File.exist?(rails_bin)
+        raise LoadError, "rails_boot: true but no bin/rails found in #{@app_path} -- this doesn't look like a " \
+                         "Rails app."
+      end
+
+      # nosemgrep: ruby.lang.security.dangerous-exec.dangerous-exec -- same rationale as execute/1 above.
+      Open3.capture3({ "RAILS_ENV" => @rails_env }, @ruby_bin, "--", rails_bin, "runner", script_path,
+                     chdir: @app_path)
+    end
+
+    def bundler_project?
+      File.exist?(File.join(@app_path, "Gemfile"))
+    end
+
+    def require_lines(paths)
+      paths.map { |path| "require #{path.inspect}" }.join("\n")
+    end
+
+    def extract_results(stdout)
+      line = stdout.lines.rfind { |l| l.start_with?(MARKER) }
+      raise LoadError, "RubyAbilityGraph runner produced no result.\n\nFull output:\n#{stdout}" unless line
+
+      JSON.parse(line.sub(MARKER, ""))
+    end
+
+    def runner_script
+      <<~RUBY
+        require "json"
+        require #{File.expand_path('role_stand_in.rb', __dir__).inspect}
+        require #{File.expand_path('enumerator.rb', __dir__).inspect}
+        #{ability_loading_lines}
+        role_stand_ins = JSON.parse(#{@roles.to_json.inspect}).transform_values do |attrs|
+          RubyAbilityGraph::RoleStandIn.new(attrs)
+        end
+        #{resolve_and_report_lines}
+      RUBY
+    end
+
+    def resolve_and_report_lines
+      <<~RUBY.chomp
+        ability_class = Object.const_get(#{@ability_class_name.inspect})
+        results = RubyAbilityGraph::Enumerator.call(ability_class: ability_class, role_stand_ins: role_stand_ins)
+        puts #{MARKER.inspect} + results.map(&:to_h).to_json
+      RUBY
+    end
+
+    def ability_loading_lines
+      @rails_boot ? rails_boot_loading_lines : plain_require_loading_lines
+    end
+
+    def rails_boot_loading_lines
+      "# rails_boot: true -- Ability file resolves via Zeitwerk autoloading, no explicit require needed. See #3."
+    end
+
+    def plain_require_loading_lines
+      ability_path = File.expand_path(@ability_file, @app_path)
+      require_paths = @requires.map { |path| File.expand_path(path, @app_path) }
+
+      <<~RUBY
+        require "cancancan"
+        #{require_lines(require_paths)}
+        require #{ability_path.inspect}
+      RUBY
+    end
+  end
+end