rigortype 0.1.5 → 0.1.6

data/lib/rigor/analysis/runner.rb

@@ -12,10 +12,13 @@ require_relative "../type/combinator"
 require_relative "../inference/coverage_scanner"
 require_relative "../inference/scope_indexer"
 require_relative "../inference/synthetic_method_scanner"
+require_relative "../inference/project_patched_scanner"
 require_relative "../inference/method_dispatcher/file_folding"
+require_relative "buffer_binding"
 require_relative "check_rules"
 require_relative "dependency_source_inference"
 require_relative "diagnostic"
+require_relative "project_scan"
 require_relative "result"
 require_relative "run_stats"
 require_relative "worker_session"
@@ -52,21 +55,63 @@ module Rigor
       #   Set to false to skip the stats summary entirely; the
       #   CLI's `--no-stats` threads `false` through to keep
       #   trivial-fixture runs from warming `.rigor/cache`.
-      def initialize(configuration:, explain: false,
+      # @param prebuilt [Rigor::Analysis::ProjectScan, nil] when
+      #   supplied, the runner adopts the pre-built plugin
+      #   registry / dependency-source index / scanner outputs
+      #   from the snapshot and skips the per-call pre-passes
+      #   that produce them. Used by long-lived integrations
+      #   (`Rigor::LanguageServer::ProjectContext`) to keep
+      #   per-buffer requests fast — scanners walk the project
+      #   once per generation rather than once per request, and
+      #   plugin `#prepare` runs once per generation rather than
+      #   once per request. Watched-file invalidation is the
+      #   owner's responsibility; the runner trusts the snapshot
+      #   it was given.
+      # @param environment [Rigor::Environment, nil] opt-in
+      #   Environment override. When supplied, sequential mode uses
+      #   the provided env instance in `#analyze_files` instead of
+      #   building a fresh one via `Environment.for_project`, and
+      #   attaches the runner's per-run reporter pair onto the
+      #   env's mutable `Reporters` slot via
+      #   `Environment#attach_reporters!`. Long-lived consumers
+      #   (LSP `ProjectContext`) pass a shared env so per-publish
+      #   work doesn't repeat the `Environment.for_project` build
+      #   (bundler / lockfile / collection discovery, RbsLoader
+      #   construction). Pool mode ignores the override — each
+      #   worker continues to build its own Environment.
+      def initialize(configuration:, explain: false, # rubocop:disable Metrics/ParameterLists
                      cache_store: Cache::Store.new(root: DEFAULT_CACHE_ROOT),
-                     plugin_requirer: nil, workers: 0, collect_stats: true)
+                     plugin_requirer: nil, workers: 0, collect_stats: true,
+                     buffer: nil, prebuilt: nil, environment: nil)
         @configuration = configuration
         @explain = explain
-        @cache_store = cache_store
+        @cache_store = enforce_read_only_cache(cache_store, buffer)
         @plugin_requirer = plugin_requirer
         @workers = workers
         @collect_stats = collect_stats
+        @buffer = buffer
+        @prebuilt = prebuilt
+        @environment_override = environment
         @plugin_registry = Plugin::Registry::EMPTY
         @dependency_source_index = DependencySourceInference::Index::EMPTY
         @rbs_extended_reporter = RbsExtended::Reporter.new
         @boundary_cross_reporter = DependencySourceInference::BoundaryCrossReporter.new
+        # `#run` resets these for each invocation; pre-seed them to
+        # empty containers so `build_run_stats` / `pre_file_diagnostics`
+        # (private, called only from `#run`) can read them without
+        # nil-guards.
+        @class_decl_paths_snapshot = {}.freeze
+        @signature_paths_snapshot = [].freeze
+        @cached_plugin_prepare_diagnostics = [].freeze
+        @project_discovered_classes = {}.freeze
       end
 
+      # ADR-pending editor mode — present when the runner is wired
+      # for the `--tmp-file` / `--instead-of` buffer-binding shape
+      # (`docs/design/20260516-editor-mode.md`). Nil for normal
+      # project runs.
+      attr_reader :buffer
+
       # Walks every Ruby file under `paths`, parses it, builds a
       # per-node scope index through
       # `Rigor::Inference::ScopeIndexer`, and runs the
@@ -84,23 +129,18 @@ module Rigor
         target_ruby_error = validate_target_ruby
         return Result.new(diagnostics: [target_ruby_error]) if target_ruby_error
 
-        @plugin_registry = load_plugins
-        @dependency_source_index = DependencySourceInference::Builder.build(@configuration.dependencies)
         expansion = expand_paths(paths)
         @class_decl_paths_snapshot = {}.freeze
         @signature_paths_snapshot = []
-        # ADR-16 slice 2b — Tier C pre-pass. Built once per run
-        # against the resolved file set + the loaded plugin
-        # registry's `heredoc_templates` so synthetic methods are
-        # visible cross-file when per-file inference dispatches.
-        @synthetic_method_index = Inference::SyntheticMethodScanner.scan(
-          plugin_registry: @plugin_registry,
-          paths: expansion.fetch(:files),
-          environment: nil
-        )
+
+        if @prebuilt
+          adopt_prebuilt_project_scan(@prebuilt)
+        else
+          run_project_pre_passes(expansion: expansion)
+        end
 
         diagnostics = pre_file_diagnostics(expansion)
-        diagnostics += analyze_files(expansion.fetch(:files))
+        diagnostics += analyze_files(target_files(expansion))
         diagnostics += rbs_extended_reporter_diagnostics
         diagnostics += boundary_cross_diagnostics
 
@@ -110,6 +150,113 @@ module Rigor
         )
       end
 
+      # Runs every project-wide pre-pass (`load_plugins` +
+      # `plugin#prepare` + dependency-source builder +
+      # synthetic-method scanner + project-patched scanner)
+      # exactly once, then returns a frozen
+      # {Rigor::Analysis::ProjectScan} snapshot.
+      #
+      # Long-lived integrations (`Rigor::LanguageServer::ProjectContext`)
+      # call this once per project-state generation and feed the
+      # snapshot back into `Runner.new(prebuilt: scan)` for every
+      # subsequent per-buffer publish. The cold pre-pass cost is
+      # paid once per generation rather than once per keystroke.
+      #
+      # Notes for callers:
+      # - The runner this method is called on may be a "build only"
+      #   instance — `@buffer` is typically nil so the scanners
+      #   observe on-disk bytes for the full project. Callers that
+      #   want pre-passes to see a particular buffer's edits should
+      #   build the runner WITH `buffer:` set.
+      # - The returned ProjectScan is frozen and shareable; the
+      #   underlying `plugin_registry` is the same object that ran
+      #   `#prepare`, so the per-plugin `services.fact_store` is
+      #   already populated for subsequent dispatch use.
+      def prepare_project_scan(paths: @configuration.paths)
+        expansion = expand_paths(paths)
+        run_project_pre_passes(expansion: expansion)
+        ProjectScan.new(
+          plugin_registry: @plugin_registry,
+          dependency_source_index: @dependency_source_index,
+          synthetic_method_index: @synthetic_method_index,
+          project_patched_methods: @project_patched_methods,
+          plugin_prepare_diagnostics: @cached_plugin_prepare_diagnostics.dup.freeze,
+          pre_eval_diagnostics: @pre_eval_diagnostics_from_scanner.dup.freeze
+        )
+      end
+
+      # Internal: drives every project-wide pre-pass and stores
+      # the results on instance variables in the order the
+      # downstream `#run` body expects. Extracted so
+      # `#prepare_project_scan` and the prebuilt-less `#run` path
+      # share one implementation.
+      def run_project_pre_passes(expansion:)
+        @plugin_registry = load_plugins
+        @dependency_source_index = DependencySourceInference::Builder.build(@configuration.dependencies)
+        # ADR-18 slice 3 — plugin prepare MUST run before the
+        # synthetic-method scanner so cross-plugin facts
+        # (`:dry_type_aliases` etc.) are already published when
+        # the scanner resolves Tier C `returns_from_arg:`
+        # lookups. The diagnostics produced by prepare are
+        # captured here so `pre_file_diagnostics` can re-emit
+        # them in the existing order without invoking prepare
+        # twice. Pool mode still re-runs prepare per worker
+        # (workers don't see this early invocation), preserving
+        # the existing Phase 4b contract.
+        @cached_plugin_prepare_diagnostics =
+          pool_mode? ? [] : plugin_prepare_diagnostics
+        # ADR-16 slice 2b — Tier C pre-pass. Built once per run
+        # against the resolved file set + the loaded plugin
+        # registry's `heredoc_templates` so synthetic methods are
+        # visible cross-file when per-file inference dispatches.
+        @synthetic_method_index = Inference::SyntheticMethodScanner.scan(
+          plugin_registry: @plugin_registry,
+          paths: expansion.fetch(:files),
+          environment: nil,
+          fact_store: shared_fact_store,
+          buffer: @buffer
+        )
+        # ADR-17 slice 2 — pre-eval pre-pass. Built once per run
+        # from the `pre_eval:` entries that exist on disk
+        # (slice-1's `pre-eval.file-not-found` `:error` already
+        # surfaced any missing entries; the scanner skips them
+        # here). The resulting {ProjectPatchedMethods} registry
+        # is consulted by the dispatcher tier between plugins
+        # and dependency-source inference so project-side
+        # patches resolve cross-file.
+        existing_pre_eval = @configuration.pre_eval.select { |path| File.file?(path) }
+        pre_eval_outcome = Inference::ProjectPatchedScanner.scan(existing_pre_eval, buffer: @buffer)
+        @project_patched_methods = pre_eval_outcome.registry
+        @pre_eval_diagnostics_from_scanner = pre_eval_outcome.diagnostics
+        # Cross-file class discovery — walks every project file
+        # for `class Foo` / `module Bar` declarations so a
+        # `Foo.method_call` receiver in one file resolves a
+        # `class Foo` declared in a sibling file. Without this
+        # pre-pass each file's `discovered_classes` was per-file
+        # only, and lexical lookup fell back to stdlib `::Foo`
+        # for any user class shadowing a stdlib name (e.g.
+        # `Google::Cloud::Storage::File`). Cost is one extra
+        # parse pass over the project; small projects pay
+        # tens of ms, larger projects ~1s. Future optimisation
+        # can share parses with the existing scanner passes.
+        @project_discovered_classes =
+          Inference::ScopeIndexer.discovered_classes_for_paths(expansion.fetch(:files), buffer: @buffer)
+      end
+
+      # Internal: adopts a frozen {ProjectScan} snapshot supplied
+      # to `Runner.new(prebuilt: ...)` by storing each slot on
+      # the runner's ivar surface, mirroring what
+      # `run_project_pre_passes` would have produced.
+      def adopt_prebuilt_project_scan(scan)
+        @plugin_registry = scan.plugin_registry
+        @dependency_source_index = scan.dependency_source_index
+        @synthetic_method_index = scan.synthetic_method_index
+        @project_patched_methods = scan.project_patched_methods
+        @cached_plugin_prepare_diagnostics = scan.plugin_prepare_diagnostics
+        @pre_eval_diagnostics_from_scanner = scan.pre_eval_diagnostics
+      end
+      private :run_project_pre_passes, :adopt_prebuilt_project_scan
+
       # ADR-15 Phase 4b — routes per-file analysis to either the
       # sequential coordinator-side Environment (legacy path,
       # default) or a Ractor worker pool built around
@@ -133,7 +280,7 @@ module Rigor
         if pool_mode?
           analyze_files_in_pool(files)
         else
-          environment = build_runner_environment
+          environment = resolve_sequential_environment
           result = files.flat_map { |path| analyze_file(path, environment) }
           if @collect_stats
             loader = environment.rbs_loader
@@ -144,6 +291,23 @@ module Rigor
         end
       end
 
+      # Sequential-mode environment resolver. Returns the supplied
+      # `environment:` override (with the runner's fresh per-run
+      # reporter pair attached so dispatcher events route to THIS
+      # runner's diagnostics) when present; otherwise builds a
+      # fresh Environment per-call via {#build_runner_environment}
+      # — preserving the pre-override behaviour bit-for-bit.
+      def resolve_sequential_environment
+        return build_runner_environment unless @environment_override
+
+        @environment_override.attach_reporters!(
+          rbs_extended_reporter: @rbs_extended_reporter,
+          boundary_cross_reporter: @boundary_cross_reporter
+        )
+        @environment_override
+      end
+      private :resolve_sequential_environment
+
       # Pre-file diagnostic streams that fire once per run rather
       # than per analyzed file: plugin load / prepare envelopes,
       # the ADR-10 dependency-source resolution surface, and the
@@ -162,9 +326,15 @@ module Rigor
       # against the coordinator-side plugin instances (which
       # the pool path never consults for per-file analysis).
       def pre_file_diagnostics(expansion)
-        prepare = pool_mode? ? [] : plugin_prepare_diagnostics
+        # ADR-18 slice 3 — prepare diagnostics are captured
+        # earlier in #run (before the synthetic-method scanner)
+        # so cross-plugin facts are available to the scanner.
+        # We re-surface the captured diagnostics here so the
+        # existing pre_file_diagnostics ordering is preserved.
+        prepare = pool_mode? ? [] : @cached_plugin_prepare_diagnostics
         plugin_load_diagnostics +
           prepare +
+          pre_eval_diagnostics +
           dependency_source_diagnostics +
           dependency_source_budget_diagnostics +
           dependency_source_config_conflict_diagnostics +
@@ -172,6 +342,53 @@ module Rigor
           expansion.fetch(:errors)
       end
 
+      # Returns the per-run shared `Plugin::FactStore` instance.
+      # All loaded plugins share this store through their
+      # respective `Plugin::Services` (the same instance is
+      # threaded by `Plugin::Loader.load`). Returns `nil` when
+      # no plugins are loaded.
+      def shared_fact_store
+        return nil if @plugin_registry.nil? || @plugin_registry.empty?
+
+        @plugin_registry.plugins.first&.services&.fact_store
+      end
+
+      # ADR-17 slice 1 — surface a `:error` diagnostic for each
+      # `pre_eval:` entry whose resolved path doesn't exist on
+      # disk. Loud failure mode (`:error`, not `:warning`):
+      # a missing pre_eval path is a configuration mistake the
+      # user must fix before analysis is meaningful.
+      #
+      # Slice 2 adds the `:warning` `pre-eval.parse-error`
+      # stream from the pre-pass scanner — accumulated as
+      # `@pre_eval_diagnostics_from_scanner` during {#run} and
+      # merged here so both diagnostics flow through the same
+      # severity / ordering pipeline.
+      def pre_eval_diagnostics
+        not_found = @configuration.pre_eval.filter_map do |path|
+          next if File.file?(path)
+
+          Diagnostic.new(
+            path: ".rigor.yml", line: 1, column: 1,
+            message: "pre_eval entry not found: #{path.inspect}. " \
+                     "Pre-evaluation requires the file to exist on disk; remove the entry " \
+                     "or create the file before re-running analysis.",
+            severity: :error,
+            rule: "pre-eval.file-not-found",
+            source_family: :builtin
+          )
+        end
+        not_found + Array(@pre_eval_diagnostics_from_scanner).map { |hash| diagnostic_from_hash(hash) }
+      end
+
+      def diagnostic_from_hash(hash)
+        Diagnostic.new(
+          path: hash.fetch(:path), line: hash.fetch(:line), column: hash.fetch(:column),
+          message: hash.fetch(:message), severity: hash.fetch(:severity),
+          rule: hash.fetch(:rule), source_family: :builtin
+        )
+      end
+
       # `target_ruby` flows through to Prism's `version:` option.
       # Prism enforces the supported range and raises
       # `ArgumentError` for versions it does not recognise. Run a
@@ -193,8 +410,54 @@ module Rigor
 
       private
 
+      # Editor mode § "Scope choice — option A". Under
+      # `buffer:` non-nil the per-file analysis emits diagnostics
+      # ONLY for the buffer's logical path; the rest of `paths:`
+      # is consumed by the project-wide pre-passes (synthetic
+      # methods, project-patched methods, plugin facts) but
+      # contributes no per-file diagnostics. This is the v1 cut
+      # before a per-file diagnostic cache exists; option B (full
+      # project + incremental cache) is queued.
+      #
+      # The buffer's logical path is added to the file list even
+      # if it's not under `paths:` — per design § "Failure
+      # envelope": "--instead-of=Y with Y not under any paths:
+      # directory → treated as a valid logical identity for the
+      # buffer".
+      def target_files(expansion)
+        files = expansion.fetch(:files)
+        return files if @buffer.nil?
+
+        [@buffer.logical_path]
+      end
+
+      # Editor mode (`buffer:` non-nil) auto-flips the cache store
+      # to `read_only: true` so multiple debounced editor invocations
+      # against the same project don't churn the on-disk cache or
+      # race on schema-version writes. Cache reads continue
+      # unchanged; misses still run the producer block but the
+      # result is not persisted. Per design doc § "Cache behaviour".
+      def enforce_read_only_cache(cache_store, buffer)
+        return cache_store if buffer.nil?
+        return cache_store if cache_store.nil?
+        return cache_store if cache_store.read_only?
+
+        Cache::Store.new(root: cache_store.root, read_only: true)
+      end
+
+      # ADR-15 Phase 4b — pool mode is enabled when `@workers > 0`.
+      # Editor mode (`buffer:` non-nil) silently overrides pool
+      # mode to sequential: per design § "Ractor pool mode", the
+      # pool's warm-up cost dominates one-file wall time, so the
+      # pool gains nothing on a per-buffer invocation. The override
+      # is part of the contract — not a degradation diagnostic —
+      # because `--workers=N` is a project-scale knob and editor
+      # mode is per-buffer; the conflict resolves toward the more
+      # specific axis.
       def pool_mode?
-        @workers.is_a?(Integer) && @workers.positive?
+        return false unless @workers.is_a?(Integer) && @workers.positive?
+
+        @buffer.nil?
       end
 
       # Coordinator-side Environment used by the sequential code
@@ -214,7 +477,8 @@ module Rigor
           bundler_lockfile: @configuration.bundler_lockfile,
           rbs_collection_lockfile: @configuration.rbs_collection_lockfile,
           rbs_collection_auto_detect: @configuration.rbs_collection_auto_detect,
-          synthetic_method_index: @synthetic_method_index
+          synthetic_method_index: @synthetic_method_index,
+          project_patched_methods: @project_patched_methods
         )
       end
 
@@ -345,7 +609,7 @@ module Rigor
       # Wall + RSS are single syscalls; total cost is bounded
       # by the snapshot size (~1000-2000 entries).
       def build_run_stats(wall_started_at:, expansion:)
-        snapshot = @class_decl_paths_snapshot || {}.freeze
+        snapshot = @class_decl_paths_snapshot
         project_sig, bundled = RunStats.partition_classes(
           class_decl_paths: snapshot,
           signature_paths: @signature_paths_snapshot
@@ -895,7 +1159,11 @@ module Rigor
         Array(paths).each do |path|
           if File.directory?(path)
             files.concat(reject_excluded(Dir.glob(File.join(path, RUBY_GLOB))))
-          elsif File.file?(path) && path.end_with?(".rb")
+          # Editor-mode bypass: the buffer's logical path is treated
+          # as a real `.rb` file regardless of on-disk presence —
+          # `parse_source` reads bytes from the buffer's physical
+          # path. Common case: LSP client editing a brand-new file.
+          elsif accept_as_ruby_file?(path)
             files << path
           elsif File.exist?(path)
             errors << path_error(path, "not a Ruby file (expected `.rb` or a directory)")
@@ -906,6 +1174,11 @@ module Rigor
         { files: files, errors: errors }
       end
 
+      def accept_as_ruby_file?(path)
+        (File.file?(path) && path.end_with?(".rb")) ||
+          (@buffer && path == @buffer.logical_path)
+      end
+
       # `Configuration#exclude_patterns` is a list of glob patterns
       # checked against each globbed path via `File.fnmatch?` (without
       # `FNM_PATHNAME`, so `**` and `*` both span path separators —
@@ -935,11 +1208,25 @@ module Rigor
         )
       end
 
+      # Reads + parses the source at `path`. Under editor mode
+      # (`@buffer` set) reads bytes from `@buffer.physical_path`
+      # when `path` matches the logical binding, then parses with
+      # `filepath: path` so Prism's location data carries the
+      # LOGICAL path. Non-binding paths go through the cheaper
+      # `Prism.parse_file` codepath unchanged.
+      def parse_source(path)
+        physical = @buffer ? @buffer.resolve(path) : path
+        return Prism.parse_file(physical, version: @configuration.target_ruby) if physical == path
+
+        Prism.parse(File.read(physical), filepath: path, version: @configuration.target_ruby)
+      end
+
       def analyze_file(path, environment) # rubocop:disable Metrics/MethodLength
-        parse_result = Prism.parse_file(path, version: @configuration.target_ruby)
+        parse_result = parse_source(path)
         return parse_diagnostics(path, parse_result) unless parse_result.errors.empty?
 
         scope = Scope.empty(environment: environment, source_path: path)
+        scope = scope.with_discovered_classes(@project_discovered_classes) unless @project_discovered_classes.empty?
         index = Inference::ScopeIndexer.index(parse_result.value, default_scope: scope)
         diagnostics = CheckRules.diagnose(
           path: path,

data/lib/rigor/analysis/worker_session.rb

@@ -88,10 +88,11 @@ module Rigor
       #   directly-unrecognised node, mirroring
       #   {Rigor::Analysis::Runner#explain_diagnostics}.
       def initialize(configuration:, cache_store: nil, # rubocop:disable Metrics/MethodLength
-                     plugin_blueprints: [], explain: false)
+                     plugin_blueprints: [], explain: false, buffer: nil)
         @configuration = configuration
         @cache_store = cache_store
         @explain = explain
+        @buffer = buffer
 
         # NOTE: `Inference::MethodDispatcher::FileFolding.fold_platform_specific_paths`
         # is process-global state. Writing it from a non-main
@@ -137,7 +138,7 @@ module Rigor
       # profile re-stamping is intentionally NOT applied — that
       # is a per-run aggregate concern handled by the caller.
       def analyze(path)
-        parse_result = Prism.parse_file(path, version: @configuration.target_ruby)
+        parse_result = parse_source(path)
         return parse_diagnostics(path, parse_result) unless parse_result.errors.empty?
 
         scope = Scope.empty(environment: @environment, source_path: path)
@@ -174,6 +175,17 @@ module Rigor
 
       private
 
+      # See {Runner#parse_source}. Same contract: if `@buffer`
+      # binds `path` to a physical file, read the physical bytes
+      # but stamp the parse buffer's `filepath:` as the LOGICAL
+      # path so downstream diagnostics carry the logical path.
+      def parse_source(path)
+        physical = @buffer ? @buffer.resolve(path) : path
+        return Prism.parse_file(physical, version: @configuration.target_ruby) if physical == path
+
+        Prism.parse(File.read(physical), filepath: path, version: @configuration.target_ruby)
+      end
+
       # Mirrors {Runner#build_trust_policy}. Workers under Phase
       # 4b will need the same trust derivation, and the
       # configuration is already shareable, so deriving it inside