rigortype 0.2.5 → 0.2.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ce4071258582638c452079484534e58c6d6b290a88ea51fdce715024d7c09297
-  data.tar.gz: 90197cb4711899857c8d242470b063e7da64947e46e240253206179a0e8f6baf
+  metadata.gz: 97d286eb15708fc212260925d407b48926a331798f0d2f210321b1d3c66cda55
+  data.tar.gz: 9fadaf2c31394c142dd15b335dbf740774ceabff8ce85b8a79fcd7faa26ea4fa
 SHA512:
-  metadata.gz: 4e967fdc0ca679a712860a20da09842c2668727c0068a4ed9657ae4111d0d94a5ab8efa9684c1a75b1ad25dbeb03efd9a4580f85e771aa5a61a05f56f38b6203
-  data.tar.gz: 8773e6364390cb36296345c4ec8974cee5bec585f7f9da292950859e4cb754081a68130db00dbc14f62d77c7f396477adace7480500d789bb838777ea268c6a2
+  metadata.gz: 1b800eb64d10fdef9039ed429f5740f672cdf0811de86c1cac1434b6bb5a0c820df68d8d8b01aa03ed0cab518d18a6e51af12d608cf6ad50556e4b653a4d3ed6
+  data.tar.gz: 5bee1c072412f7eac14d0c96314f8efe2473cd46efe9763e238bd3c345605deb29055db3601c52909c430d419d8821fc7befb51fe0f5211b8fbb94e379a5d635

data/docs/handbook/09-plugins.md

@@ -68,12 +68,15 @@ directory — gives a plugin five primary surfaces:
    array of `Rigor::Analysis::Diagnostic` rows. The runner
    stamps each with `source_family: "plugin.<your-id>"`.
 2. **`dynamic_return(receivers:, methods:, file_methods:)` /
-   `type_specifier(methods:)`** — the per-call-site return-type
+   `narrowing_facts(methods:)`** — the per-call-site return-type
    and flow-narrowing contribution surface (ADR-37 Slice 2).
    A `dynamic_return` block names the inferred return type at a
    matching call site; the analyzer's dispatcher merges the
    contribution and uses it as if it were RBS-declared. A
-   `type_specifier` block contributes branch-narrowing facts.
+   `narrowing_facts` block contributes branch-narrowing facts.
+   (`narrowing_facts` was renamed from `type_specifier` in ADR-80;
+   `type_specifier` remains as a deprecating alias removed in 0.3.0,
+   so use `narrowing_facts` in new plugins.)
    (These replaced the removed `flow_contribution_for` hook —
    ADR-52 WD3; a plugin that still defines it raises at load.)
 3. **`Plugin::IoBoundary#read_file`** / **`#open_url`** —

data/docs/handbook/appendix-liskov.md

@@ -210,10 +210,12 @@ def shout(thing)
 end
 
 # Clause 1 / covariant returns: the body provably returns the
-# receiver, so #dup returns `self` (Array, not the widened Object).
-# Returning Object would *weaken* the postcondition.
+# receiver, so #dup returns `self` (the receiver's own type, not the
+# widened Object). Returning Object would *weaken* the postcondition.
+# Shape preservation through `dup` (ADR-76 WD2) keeps the precise
+# tuple here rather than degrading to the nominal `Array`.
 copy = [1, 2, 3].dup
-assert_type("Array", copy)
+assert_type("[1, 2, 3]", copy)
 ```
 
 The connection to the type-theory appendix's **gradual guarantee**

data/docs/handbook/appendix-phpstan.md

@@ -96,13 +96,13 @@ When the assertion is recognised by **call shape** rather than
 by signature — PHPStan's `TypeSpecifyingExtension` interface,
 where you write a class that the framework instantiates and
 asks "given this call, what narrowings does it produce?" —
-Rigor's analogue is a plugin's `type_specifier` / `dynamic_return` and
+Rigor's analogue is a plugin's `narrowing_facts` / `dynamic_return` and
 `#diagnostics_for_file` hooks plus the engine's
 `post_return_facts` substrate.
 
 | PHPStan extension type | Rigor analogue |
 | --- | --- |
-| `MethodTypeSpecifyingExtension` | Plugin's `Fact(target_kind: :parameter)` returned from `type_specifier` |
+| `MethodTypeSpecifyingExtension` | Plugin's `Fact(target_kind: :parameter)` returned from `narrowing_facts` |
 | `StaticMethodTypeSpecifyingExtension` | Same, with `Fact(target_kind: :receiver-class)` |
 | `FunctionTypeSpecifyingExtension` | Same, with `Fact(target_kind: :argument)` |
 | `DynamicMethodReturnTypeExtension` | Plugin's `dynamic_return(methods:) { |call_node, scope, ...| ... }` |

data/docs/install.md

@@ -152,7 +152,7 @@ without WSL). For all other environments, prefer Case A–D above.
 rigor --version
 ```
 
-A version string like `rigor 0.1.x` confirms a successful install.
+A version string like `rigor 0.2.x` confirms a successful install.
 If the command is not found, revisit Step 2 for your case.
 
 ---

data/docs/manual/02-cli-reference.md

@@ -403,7 +403,7 @@ catalogue** ([ADR-37](../adr/37-plugin-interface-segregation.md)):
 a focused, machine-readable map of what each loaded plugin
 contributes — the AST node types its `node_rule`s match, the
 receiver classes its `dynamic_return`s gate on, the methods its
-`type_specifier`s narrow, and the facts it `produces` /
+`narrowing_facts`s narrow, and the facts it `produces` /
 `consumes`. Combine with `--format=json` for tooling (an AI
 agent can enumerate every plugin's behaviour without reading a
 line of plugin source). The same narrow surfaces also appear in
@@ -539,6 +539,63 @@ with its stable id, the severity it would impose, and whether your config
 adopts it. See [`docs/compatibility.md`](../compatibility.md) for how
 bleeding-edge fits the stability model.
 
+## `rigor doctor`
+
+Classify setup problems vs a clean run with routed next actions
+([ADR-77](../adr/77-doctor-and-upgrade-commands.md) WD1).
+
+```sh
+rigor doctor [--config PATH] [--format text|json]
+```
+
+| Flag | Purpose |
+| --- | --- |
+| `--config PATH` | Use this `.rigor.yml` instead of auto-discovery. |
+| `--format text\|json` | Output format. Default `text`. |
+
+Runs a scoped analysis and audits:
+
+- **Configuration audit** — unresolved `signature_paths:`, unknown
+  `libraries:`, inert `disable:` / `severity_overrides:` tokens
+  ({ConfigAudit}).
+- **RBS environment health** — whether the RBS class universe built
+  successfully (`0` classes means a broken setup).
+- **Plugin load errors** — whether every configured plugin loaded.
+- **Baseline drift** — whether the current diagnostics have drifted
+  from the saved baseline.
+- **Rails plugin gap** — whether `Gemfile.lock` contains Rails gems
+  but no Rails plugin is enabled.
+
+Text output prints `[PASS]`, `[FAIL]`, or `[WARN]` per check plus a
+routed hint (e.g. "Run `rigor baseline regenerate`").  JSON output
+is a stable contract:
+
+```json
+{
+  "status": "issues_found",
+  "checks": [
+    { "id": "config_audit", "status": "fail", "message": "...", "hint": "..." }
+  ]
+}
+```
+
+Exits `1` when any check fails, `0` when all pass.
+
+## `rigor upgrade`
+
+Migration command skeleton ([ADR-50](../adr/50-release-engineering-and-stability-strategy.md)
+WD7).  The real body lands when a concrete backwards-compatibility
+break gives it a target (e.g. re-running `baseline regenerate`
+against a strengthened default profile, surfacing renamed
+suppression ids, reporting `bleeding_edge:` graduations).
+
+```sh
+rigor upgrade
+```
+
+Until then it prints the current version and notes that upgrade is
+queued.  Exits `0`.
+
 ## Environment variables
 
 Most behaviour is driven by flags and `.rigor.yml`; a few

data/docs/manual/06-baseline.md

@@ -77,6 +77,18 @@ a diagnostic another layer has already suppressed.
 default — one bucket per file × rule) or `--match-mode=message`
 (a bucket per distinct message: more precise, more churn).
 
+`--match-mode=message` keys each bucket on the **rendered
+message text**, which includes details such as the displayed
+receiver type. That makes it sharper at telling two same-rule
+diagnostics on one line apart, but also **brittle**: when a Rigor
+upgrade rewords a message or changes how a type is displayed, the
+key no longer matches and the previously-baselined diagnostic
+resurfaces as if new. `--match-mode=rule` keys only on
+`(file, rule)` and is immune to message rewording — prefer it
+unless you specifically need per-message discrimination, and
+expect to `regenerate` a `message`-mode baseline after upgrading
+Rigor.
+
 ## Working a baseline down
 
 `rigor triage` summarises a diagnostic stream — rule

data/docs/manual/11-ci.md

@@ -192,9 +192,9 @@ remains available for any other tool that wants the raw diagnostic stream.
 
 The workflow above installs whatever `rigortype` is current at run
 time. To pin a version — and keep CI reproducible — choose one of the
-options below. While the `0.1.x` line is in preview the surface is
-still settling, so pinning is recommended; what Rigor commits to
-keeping stable (and from which release) is enumerated in
+options below. While the `0.2.x` line is an evaluation trial the
+surface is still settling, so pinning is recommended; what Rigor
+commits to keeping stable (and from which release) is enumerated in
 [`docs/compatibility.md`](../compatibility.md).
 
 ### A CI-only `Gemfile` (recommended)
@@ -203,7 +203,7 @@ Commit a two-line `.github/rigor/Gemfile`:
 
 ```ruby
 source "https://rubygems.org"
-gem "rigortype", "~> 0.1"
+gem "rigortype", "~> 0.2"
 ```
 
 plus its `Gemfile.lock`, and point the Rigor job at it through
@@ -242,7 +242,7 @@ updates:
 
 ### A pinned `gem install`
 
-`gem install rigortype -v "0.1.15"` in the workflow. Simpler, with no
+`gem install rigortype -v "0.2.6"` in the workflow. Simpler, with no
 extra files — but Dependabot does not see a version inside a `run:`
 step, so updates to the pin are manual.
 
@@ -258,7 +258,7 @@ docker run --rm -v "$PWD:/src" ghcr.io/rigortype/rigor check
 
 `rigor` is the image entrypoint, so subcommands and flags follow the
 image name. Pin a version with an explicit tag —
-`ghcr.io/rigortype/rigor:0.1.15`.
+`ghcr.io/rigortype/rigor:0.2.6`.
 
 ## Nix
 

data/docs/manual/15-type-protection-coverage.md

@@ -172,6 +172,35 @@ breakage a *different* test would catch shows as a gap). For an
 accurate map, run the command over all tests that exercise the
 files you are measuring — trading time for completeness.
 
+### Why a hole is untyped — provenance and tractability
+
+For a `Dynamic`-receiver hole, `rigor coverage --protection` also
+records *why* the receiver is untyped and *whether a type can close
+it*, so you spend effort where it pays off. Each `add_a_type_here`
+entry carries two fields:
+
+- **`dynamic_origin`** — the cause the value became dynamic:
+  `external_gem_without_rbs`, `framework_dsl_boundary`,
+  `analyzer_budget_cutoff`, `explicit_untyped`, or
+  `unsupported_syntax`.
+- **`tractability`** — the action axis derived from that cause:
+  - **`add_rbs`** — you can close it with a type: install RBS
+    (`rbs collection install`), enable `dependencies.source_inference:`,
+    or tighten an authored `untyped` signature.
+  - **`enable_plugin`** — a framework / DSL boundary; reach for a
+    plugin or [`pre_eval:`](03-configuration.md), not a hand-written
+    type.
+  - **`engine_gap`** — not closable by a user type (a budget cutoff
+    or a construct Rigor does not yet model); report it.
+
+The text report prints a one-line `by tractability:` breakdown under
+the "Add a type here" header, and the JSON carries the same totals as
+`tractability_summary`. Start with the `add_rbs` holes — they are the
+ones a type actually catches.
+
+Provenance is precision-additive only: it never changes a type, fires
+no diagnostic, and never affects severity or the protection ratio.
+
 ## Cost and scope
 
 The fused tiers run real analyses and real test suites, so treat

data/docs/manual/plugins/rigor-minitest.md

@@ -79,7 +79,7 @@ matches.
 ## Plugin internals
 
 The assertion recogniser and the contract surfaces this plugin
-exercises — the ADR-37 `type_specifier` narrowing gate and the ADR-38
+exercises — the ADR-37 `narrowing_facts` narrowing gate and the ADR-38
 `additional_initializers` for `setup` — are in the
 [plugin's README](../../../plugins/rigor-minitest/README.md). To write a
 plugin, see [`examples/`](../../../examples/README.md) and the

data/lib/rigor/cli/check_command.rb

@@ -13,6 +13,7 @@ require_relative "command"
 require_relative "options"
 require_relative "diagnostic_formats"
 require_relative "ci_detector"
+require_relative "check_runner_factory"
 
 module Rigor
   class CLI
@@ -244,42 +245,12 @@ module Rigor
       end
 
       def build_check_runner(configuration:, options:, buffer:, cache_root:)
-        cache_store = if options.fetch(:no_cache)
-                        nil
-                      else
-                        Cache::Store.new(
-                          root: cache_root,
-                          max_bytes: configuration.cache_max_bytes
-                        )
-                      end
-        Analysis::Runner.new(
-          configuration: configuration,
-          explain: options.fetch(:explain),
-          cache_store: cache_store,
-          collect_stats: options.fetch(:stats),
-          workers: resolve_workers(options, configuration),
-          buffer: buffer
+        CheckRunnerFactory.build(
+          configuration: configuration, options: options,
+          buffer: buffer, cache_root: cache_root
         )
       end
 
-      # ADR-15 Phase 4c — resolves the worker count by
-      # precedence: CLI `--workers=N` (most explicit) > env
-      # `RIGOR_RACTOR_WORKERS` > config `.rigor.yml`
-      # `parallel.workers:` > 0 (sequential default). Returns
-      # an Integer; non-numeric values raise so typos fail
-      # loudly. CLI / env may pass a negative value — clamped
-      # to 0 (sequential) so a stray `-1` doesn't crash the
-      # pool spawn loop.
-      def resolve_workers(options, configuration)
-        cli_value = options[:workers]
-        return [Integer(cli_value), 0].max if cli_value
-
-        env_value = ENV.fetch("RIGOR_RACTOR_WORKERS", nil)
-        return [Integer(env_value), 0].max if env_value && !env_value.empty?
-
-        configuration.parallel_workers
-      end
-
       def parse_check_options # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
         options = {
           config: nil,

data/lib/rigor/cli/check_runner_factory.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require_relative "../analysis/runner"
+require_relative "../cache/store"
+
+module Rigor
+  class CLI
+    # Shared factory for building an {Analysis::Runner} from CLI option
+    # hashes + a loaded {Configuration}.
+    #
+    # Extracted from {CheckCommand} so that `rigor doctor` and future
+    # `describe --deep` can reuse the exact same runner-setup logic
+    # (cache, workers, buffer, explain) without diverging from the
+    # primary check path (ADR-77 WD3).
+    module CheckRunnerFactory
+      module_function
+
+      # Builds a runner matching the configuration/plugin/cache resolution
+      # that `rigor check` itself uses.
+      #
+      # @param configuration [Rigor::Configuration]
+      # @param options [Hash] parsed CLI options (must contain at least
+      #   `:no_cache`, `:explain`, `:stats`, `:workers`)
+      # @param buffer [Rigor::Analysis::BufferBinding, nil]
+      # @param cache_root [String]
+      # @return [Rigor::Analysis::Runner]
+      def build(configuration:, options:, buffer:, cache_root:)
+        cache_store = if options.fetch(:no_cache)
+                        nil
+                      else
+                        Cache::Store.new(
+                          root: cache_root,
+                          max_bytes: configuration.cache_max_bytes
+                        )
+                      end
+        Analysis::Runner.new(
+          configuration: configuration,
+          explain: options.fetch(:explain),
+          cache_store: cache_store,
+          collect_stats: options.fetch(:stats),
+          workers: resolve_workers(options, configuration),
+          buffer: buffer
+        )
+      end
+
+      # Resolves the worker count by precedence: CLI `--workers=N`
+      # (most explicit) > env `RIGOR_RACTOR_WORKERS` > config
+      # `.rigor.yml` `parallel.workers:` > 0 (sequential default).
+      # Returns an Integer; non-numeric values raise so typos fail
+      # loudly. CLI / env may pass a negative value — clamped to 0
+      # (sequential) so a stray `-1` doesn't crash the pool spawn loop.
+      def resolve_workers(options, configuration)
+        cli_value = options[:workers]
+        return [Integer(cli_value), 0].max if cli_value
+
+        env_value = ENV.fetch("RIGOR_RACTOR_WORKERS", nil)
+        return [Integer(env_value), 0].max if env_value && !env_value.empty?
+
+        configuration.parallel_workers
+      end
+    end
+  end
+end

data/lib/rigor/cli/doctor_command.rb

@@ -0,0 +1,295 @@
+# frozen_string_literal: true
+
+require "json"
+require "optionparser"
+
+require_relative "../configuration"
+require_relative "../config_audit"
+require_relative "../analysis/baseline"
+require_relative "../analysis/result"
+require_relative "../plugin"
+require_relative "../plugin/loader"
+require_relative "../plugin/services"
+require_relative "../reflection"
+require_relative "../type/combinator"
+require_relative "check_runner_factory"
+require_relative "command"
+require_relative "options"
+
+module Rigor
+  class CLI
+    # `rigor doctor` — classify existing project findings into setup-problem
+    # vs clean-run with a routed next action (ADR-77 WD1).
+    #
+    # It is a presentation/aggregation layer over data `rigor check` already
+    # produces — no new analysis pass and no new diagnostic rule.  The
+    # command runs a scoped analysis to gather stats, audits the
+    # configuration, validates plugins, and checks baseline drift, then
+    # reports a small fixed set of checks with a hint for each failure.
+    class DoctorCommand < Command # rubocop:disable Metrics/ClassLength
+      USAGE = "Usage: rigor doctor [options]"
+
+      # Check identifiers — the stable JSON contract (`checks[].id`).
+      CHECK_CONFIG = "config_audit"
+      CHECK_RBS = "rbs_environment"
+      CHECK_PLUGINS = "plugins"
+      CHECK_BASELINE = "baseline"
+      CHECK_RAILS = "rails_plugins"
+
+      RAILS_LOCK_MARKERS = %w[railties actionpack activerecord actioncable].freeze
+      RAILS_PLUGIN_MARKERS = %w[
+        rigor-activerecord rigor-actionpack rigor-actionmailer rigor-activejob
+        rigor-rails-routes rigor-rails-i18n rigor-actioncable rigor-activestorage rigor-rails
+      ].freeze
+
+      # @return [Integer] CLI exit status.
+      def run
+        options = parse_options
+        configuration = Configuration.load(options.fetch(:config))
+        findings = []
+
+        # 1. Config audit (cheap — no analysis needed).
+        findings.concat(audit_config(configuration))
+
+        # 2. Run a scoped analysis to gather stats + diagnostics for the
+        #    deeper checks.  Use no-cache so the probe doesn't churn disk.
+        runner = CheckRunnerFactory.build(
+          configuration: configuration,
+          options: { no_cache: true, explain: false, stats: true, workers: 0 },
+          buffer: nil,
+          cache_root: configuration.cache_path
+        )
+        result = runner.run(configuration.paths)
+
+        # 3. RBS environment check.
+        findings.concat(check_rbs_environment(result))
+
+        # 4. Plugin load check.
+        findings.concat(check_plugins(configuration))
+
+        # 5. Baseline drift check.
+        findings.concat(check_baseline(configuration, result))
+
+        # 6. Rails locked but no Rails plugins.
+        findings.concat(check_rails_plugins(configuration))
+
+        report(findings, options.fetch(:format))
+        findings.any? { |f| f[:status] == :fail } ? 1 : 0
+      rescue OptionParser::InvalidArgument => e
+        @err.puts(e.message)
+        CLI::EXIT_USAGE
+      end
+
+      private
+
+      def parse_options
+        options = { config: nil, format: "text" }
+        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 }
+        end.parse!(@argv)
+        validate!(options)
+        options
+      end
+
+      def validate!(options)
+        return if %w[text json].include?(options.fetch(:format))
+
+        raise OptionParser::InvalidArgument, "unsupported format: #{options.fetch(:format)}"
+      end
+
+      # ------------------------------------------------------------------
+      # Individual checks — each returns an Array of finding Hashes.
+      # A finding has: :check, :status (:pass/:fail/:warn), :message, :hint
+      # ------------------------------------------------------------------
+
+      def audit_config(configuration)
+        warnings = ConfigAudit.warnings(configuration, project_root: Dir.pwd)
+        return [] if warnings.empty?
+
+        messages = warnings.map(&:message)
+        [
+          {
+            check: CHECK_CONFIG,
+            status: :fail,
+            message: "Configuration warnings: #{messages.size}",
+            hint: "Review and fix the flagged entries in your config file."
+          }
+        ]
+      end
+
+      def check_rbs_environment(result)
+        stats = result.stats
+        return [] unless stats
+
+        if stats.rbs_classes_total.zero?
+          [
+            {
+              check: CHECK_RBS,
+              status: :fail,
+              message: "RBS environment is empty (#{stats.rbs_classes_total} classes available)",
+              hint: "The RBS environment failed to build or loaded no signatures. " \
+                    "Check `signature_paths:` for duplicate declarations, or run " \
+                    "`rbs collection install` for gem signatures."
+            }
+          ]
+        else
+          [
+            {
+              check: CHECK_RBS,
+              status: :pass,
+              message: "RBS environment healthy (#{stats.rbs_classes_total} classes available)",
+              hint: nil
+            }
+          ]
+        end
+      end
+
+      def check_plugins(configuration)
+        services = Plugin::Services.new(
+          reflection: Reflection,
+          type: Type::Combinator,
+          configuration: configuration,
+          cache_store: nil
+        )
+        registry = Plugin::Loader.load(configuration: configuration, services: services)
+        errors = registry.load_errors
+        return [] if errors.empty?
+
+        [
+          {
+            check: CHECK_PLUGINS,
+            status: :fail,
+            message: "Plugin load errors: #{errors.size}",
+            hint: "Run `rigor plugins --strict` for the full per-plugin report."
+          }
+        ]
+      end
+
+      def check_baseline(configuration, result)
+        path = configuration.baseline_path
+        return [] if path.nil? || !File.exist?(path)
+
+        baseline = Analysis::Baseline.load(path, project_root: Dir.pwd)
+        return [] if baseline.nil? || baseline.empty?
+
+        drifted = baseline.audit(result.diagnostics).reject { |row| row.status == :within }
+        return [] if drifted.empty?
+
+        [
+          {
+            check: CHECK_BASELINE,
+            status: :fail,
+            message: "Baseline drift detected (#{baseline_drift_summary(drifted)})",
+            hint: "Run `rigor baseline regenerate` to refresh the baseline."
+          }
+        ]
+      rescue Analysis::Baseline::LoadError, Psych::SyntaxError => e
+        [
+          {
+            check: CHECK_BASELINE,
+            status: :warn,
+            message: "Baseline load failed: #{e.message}",
+            hint: "Check the baseline file path in your config."
+          }
+        ]
+      end
+
+      def baseline_drift_summary(drifted)
+        counts = drifted.group_by(&:status).transform_values(&:size)
+        parts = []
+        parts << "#{counts.fetch(:over, 0)} over threshold" if counts.key?(:over)
+        parts << "#{counts.fetch(:cleared, 0)} cleared" if counts.key?(:cleared)
+        parts << "#{counts.fetch(:reducible, 0)} reducible" if counts.key?(:reducible)
+        parts.join(", ")
+      end
+
+      def check_rails_plugins(configuration)
+        return [] unless rails_unconfigured?(configuration)
+
+        [
+          {
+            check: CHECK_RAILS,
+            status: :fail,
+            message: "Rails detected but no Rails plugins enabled",
+            hint: "Add Rails plugins (e.g. rigor-activerecord, rigor-actionpack) to " \
+                  "`.rigor.yml` `plugins:` so framework calls resolve."
+          }
+        ]
+      end
+
+      # True when Rails is in Gemfile.lock but the config enables no
+      # Rails plugin — the same probe {ProjectStateProbe} uses.
+      def rails_unconfigured?(_configuration)
+        config_path = Configuration.discover
+        return false if config_path.nil?
+        return false unless File.file?(config_path)
+
+        lock = File.join(Dir.pwd, "Gemfile.lock")
+        return false unless File.file?(lock) && file_mentions_any?(lock, RAILS_LOCK_MARKERS)
+
+        !file_mentions_any?(config_path, RAILS_PLUGIN_MARKERS)
+      end
+
+      def file_mentions_any?(path, markers)
+        content = File.read(path)
+        markers.any? { |marker| content.include?(marker) }
+      rescue StandardError
+        false
+      end
+
+      # ------------------------------------------------------------------
+      # Reporting
+      # ------------------------------------------------------------------
+
+      def report(findings, format)
+        case format
+        when "json" then report_json(findings)
+        else report_text(findings)
+        end
+      end
+
+      def report_json(findings)
+        payload = {
+          "status" => findings.any? { |f| f[:status] == :fail } ? "issues_found" : "clean",
+          "checks" => findings.map do |f|
+            {
+              "id" => f[:check].to_s,
+              "status" => f[:status].to_s,
+              "message" => f[:message],
+              "hint" => f[:hint]
+            }
+          end
+        }
+        @out.puts(JSON.pretty_generate(payload))
+      end
+
+      def report_text(findings)
+        failures = findings.select { |f| f[:status] == :fail }
+        warnings = findings.select { |f| f[:status] == :warn }
+        passes = findings.select { |f| f[:status] == :pass }
+
+        if failures.empty? && warnings.empty?
+          @out.puts("rigor doctor: all checks passed — no setup problems detected.")
+        else
+          @out.puts("rigor doctor: #{failures.size} issue(s) found")
+          failures.each { |f| print_finding(f) }
+          warnings.each { |f| print_finding(f) } unless warnings.empty?
+        end
+
+        passes.each { |f| print_finding(f) } unless passes.empty?
+      end
+
+      def print_finding(finding)
+        label = case finding[:status]
+                when :fail then "[FAIL]"
+                when :warn then "[WARN]"
+                else "[PASS]"
+                end
+        @out.puts("#{label} #{finding[:check]}: #{finding[:message]}")
+        @out.puts("  → #{finding[:hint]}") if finding[:hint]
+      end
+    end
+  end
+end