エディタモード — 単一ファイル高速応答解析

Status: Draft. まだスライスされていない。将来ADRが起票された場合にのみ取って代わられる。

今日のRigorはプロジェクト指向である。rigor check libはpaths:配下のすべての.rbを走査し、Environmentを1つ構築し、診断を出力する。エディタ／IDE／LSPのユースケースはその逆であり、ユーザーは単一のバッファを編集し、秒単位ではなくミリ秒単位のフィードバックを期待する。本ドキュメントは、今日フルLSPにコミットすることなくそのワークロードをサポートするためにRigorが必要とするCLI表面とランナー側の置き換えを設計する。

契約の形はPHPStanの「Editor Mode」（references/phpstan/website/src/user-guide/editor-mode.mdを参照）を踏襲する。設計上の問題が同じだからである。すなわち、エディタは未保存のバッファを保持し、外部ツールがそれをテンポラリファイルへ書き出し、解析器はそのテンポラリファイルがプロジェクト内の1つのファイルを置き換えたかのように振る舞わなければならない。

動機

ADR-0はLSP統合を意図的に先送りし、CLIファーストの推論エンジンを成熟させることを優先した。その決定は今も有効である。ただし、「CLIファースト」が「プロジェクト専用」を意味する必要はない。エディタ拡張はバッファ保存ごと／デバウンスされたキーストロークごとにシェルアウトし、診断ストリームを1つ受け取ってインライン表示すればよい。「エディタ駆動Rigor」のMVPは、バッファを受け取って当該バッファの診断を高速に返すCLI起動である。

今日「高速」が意味すること。

コールドスタート（キャッシュなし、フルプリパス）: rigor checkのプロジェクト全体セットアップコストに律速される。本設計の対象外。
ウォームスタート（キャッシュあり、他箇所のソース変更なし）: 現行ラップトップ上の5Kファイル規模プロジェクトでバッファあたり1秒未満を目標とする。単一ファイル解析パス自体はすでに高速である。ボトルネックは、バッファ1つだけ変更されたときでもRigorがプロジェクト全体を再走査することにある。

契約（CLI表面）

rigor checkは、論理的なプロジェクトパスを物理的なバッファファイルにバインドする、ペアになった2つのオプションを得る。

rigor check \
  --tmp-file=/tmp/9539itfeh2.rb \
  --instead-of=lib/foo.rb \
  lib

意味論。

--tmp-file=PATH — Rigorがバイトをパースしなければならない物理ファイル。存在し読み取り可能でなければならない。ファイルが欠けている場合は終了コード64（usage）。
--instead-of=PATH — バッファが表す論理的なプロジェクトパス。解析器はlib/foo.rbが/tmp/9539itfeh2.rbの内容を持っていたかのように振る舞う。診断はpath: lib/foo.rbを報告しなければならない（MUST）。これによりエディタは正しいバッファをハイライトする。
2つのフラグは一緒に現れなければならない（MUST）。片方だけは使用法エラー（EXIT_USAGE）。
--instead-of=PATHの元ファイルは解析されない。パス展開に含まれている場合（典型例）は、バッファを優先して暗黙にスキップされる。
マルチバッファ（--buffer A=B --buffer C=D）はv1の対象外。単一バッファコマンドはデバウンスされたキーストロークの合間にエディタが呼び出すものである。マルチバッファはLSPデーモンが保存イベントを多重化するようになって初めて興味深くなる。

同じフラグ対はrigor type-of（エディタがcheckよりも頻繁に呼び出すホバーから型を得るユースケース）にも拡張される。type-ofはPrism境界ですでにsource:とfilepath:を分離しているため、そこでの置き換えは 1行の配管変更で済む。

rigor type-scan、rigor explain、rigor diff、rigor sig-genはエディタモードのフラグを得ない。これらはプロジェクト全体またはストリーム形状のツールであり、バッファごとのプローブではない。

ランナーへの置き換えのマッピング

ランナーは今日、ファイルを3つのレイヤーで処理する。

パス展開 — Analysis::Runner#expand_pathsがpaths:リストを具体的な.rbファイルの[String]に解決する。
ファイルごとのパース — Runner#analyze_file（逐次）と WorkerSession#analyze（プールモード）が各パスに対して Prism.parse_file(path, version:)を呼ぶ。
プロジェクトプリパス — SyntheticMethodScanner、 ProjectPatchedScanner、プラグインの#prepare、依存ソースウォーカーーがそれぞれ自身の入力セットを読む。

エディタモードは3つのレイヤーすべてに適用される置き換えである。

レイヤー	逐次的な変更	理由
展開	ファイルリストでは`lib/foo.rb` → `/tmp/9539itfeh2.rb`に置き換えるが、元のパスは論理的な同一性として記憶する。	エンジンがバッファを他のファイルと同様に扱えるようにしつつ、論理パスを報告できるようにする。
パース	`Prism.parse_file(physical, version:)`もしくは`Prism.parse(File.read(physical), filepath: logical, version:)`。後者が望ましい。パース結果ソースの`filepath:`を最初から論理パスに等しくできるためである。	診断の位置情報が自動的に論理パスを使う。
プリパス	同じ置き換え。各スキャナのパースステップはバッファバインディングを認識するヘルパー1つを経由する。	プリパスはバッファのバイトを参照しなければならない。さもなくばプラグインファクト／プロジェクトパッチレジストリ／合成メソッドが進行中の編集を見逃す。

配線ポイントはBufferBindingと呼ぶ1つの値オブジェクトであり、 Runner.new(... buffer: BufferBinding.new(logical:, physical:))を通じてスレッディングされる。デフォルトをnilにすることでレガシーパスはビット単位で変わらない。

BufferBinding = Data.define(:logical_path, :physical_path) do
  def resolve(path)
    path == logical_path ? physical_path : path
  end

  def display_path(path)
    path == physical_path ? logical_path : path
  end
end

2つのヘルパー（読み込み用のresolve、診断出力用のdisplay_path）が、現在パスを消費するすべての呼び出し箇所をカバーする。既存のワンショット Diagnostic.new(path: path, ...)呼び出し箇所は、論理パスを直接渡すか（パースがすでにfilepath: logicalを見ているため）、出力前のランナー境界でbinding.display_path(path)を経由するかのいずれかになる。

キャッシュの振る舞い

PHPStanのエディタモードは結果キャッシュを復元するが保存はしない。 RigorのCache::Store（ADR-6）は内容アドレス指定でシャーディングされ、エントリーごとにflockを持つ。読み込みはロックフリーで、書き込みはエントリごとにアトミックである。2つの変更を行う。

読み取り専用モード — Cache::Store::ReadOnlyラッパー（または Storeのフラグ）が#fetch_or_computeの書き込み副作用をすべて抑制する。プロデューサーブロックはミス時には引き続き実行される。結果は呼び出し元に返されるが永続化されない。既存のディスク上エントリーはそのままヒットを提供する。
並行安全性 — 同じキャッシュルートに対する複数のエディタモード実行は安全である。書き込み手がいないためである。ADR-6のファイルごと flock不変条件は変わらない。

エディタモードは--tmp-fileがセットされたときキャッシュを自動的に読み取り専用に強制する。--no-cacheは依然として機能する（ディスク読み込みもスキップする）。

今日のRigorはファイルごとの診断キャッシュを持たない。PHPStanの「編集されたファイルのみが再解析される」速度はそれに依存しているため、今日Rigorが提供できる最速のパスは「インクリメンタルなプロジェクト」ではなく単一ファイルスコープである。後述の「スコープ選択」セクションを参照。

スコープ選択 — 何が解析されるか

実行可能な形は3つ。

（A）単一ファイルスコープ。--tmp-fileがセットされたとき、 Rigorはバッファのみを解析する。paths:の残りはEnvironmentコンテキスト（RBS、プラグインファクト、合成メソッドインデックス、プロジェクトパッチレジストリ）として読み込まれるが、他のファイルに対する診断は出力されない。
（B）バッファ置き換えを伴うプロジェクトスコープ。PHPStan形。プロジェクト全体が解析される。編集されたファイルは置き換えられる。高速化にはファイルごとの診断キャッシュが必要だが、Rigorはまだそれを持たない（ADR-17スライス3bがキューイングされたレバー）。
（C）単一ファイル＋呼び出し側が宣言した依存先。エディタはバッファの公開面（戻り型、定数値、エクスポートされたモジュール）に依存することが分かっているファイルに対して--also=lib/bar.rb,lib/baz.rbを渡す。

v1は（A）を出荷する。速度目標を達成する最小のカットであり、前方互換である。ファイルごとの診断キャッシュが存在するようになったとき、同じ CLI形状はフラグの改名なしで（B）にアップグレードできる。

エディタ拡張は単一ファイル起動を複数回（影響を受けるファイルごとに1回）発行することで（A）の上に（C）を重ねられる。Rigorはファイルごとのキャッシュが存在するまで、呼び出し側に依存追跡を提供する責務を負わない。

プロジェクトプリパスとの相互作用

SyntheticMethodScanner、ProjectPatchedScanner、プラグインの #prepare、依存ソースウォーカーはそれぞれ、ファイルごとの解析が走る前にプロジェクト全体の状態を構築する。単一ファイルエディタモードでは3つの条件が成り立たなければならない。

プリパスは論理パスにあるバッファのバイトを参照する。 BufferBinding.resolveがそれらのパースヘルパーを通じてスレッディングされる。
プリパスは入力が変わっていない場合、悲観的にキーストロークごとに再実行されない。v1は起動ごとに再実行する（小中規模プロジェクトでは安価寄りだが無料ではない）。後続作業として、（プラグインマニフェストのダイジェスト、プロジェクトファイルのmtime + サイズリスト）をキーとするプロジェクトコンテキストスナップショットキャッシュを設計する。
プラグインの#prepareはエディタモード起動ごとに1回実行される。これは今日と同じである。プラグイン横断ファクトを公開するプラグイン（:dry_type_aliases、:helper_table、:model_index）は、繰り返しのエディタモード実行が収束するように冪等でなければならない（MUST）。 ADR-9の設計によりすでに冪等である。

Ractorプールモード

ADR-15フェーズ4bのRactorプールはRBSキャッシュをウォームアップし、N個のワーカーを生成する。1ファイル実行ではプールのウォームアップコストがウォール時間を支配する。よってエディタモードは--tmp-fileがセットされているとき、--workers=N／RIGOR_RACTOR_WORKERS／parallel.workers: に関係なくworkers: 0（逐次）を強制する。このオーバーライドはサイレントである。プールモードはプロジェクト規模のつまみであり、エディタモードはバッファごとのものである。

診断の順序とインライン無効化マーカー

# rigor:disable <rule>の行末マーカーはパース結果ソースの parse_result.commentsから来る。これはバッファのソースそのものである。バッファの現在の行番号を自然に追跡する。特別な処理は不要。
プロジェクトレベルの.rigor.ymlのdisable:キーはパス非依存でありそのまま適用される。
重要度プロファイル＋ルールごとのオーバーライドはそのまま適用される。

実行統計

RunStatsはデフォルトで有効である。エディタモードでもオンのままにし、エディタのログ表面が「analysed lib/foo.rb (buffer) in N ms, wall: Xs, RBS classes: K」を表示できるようにすべきである。統計オブジェクトに新たなフィールドが1つ加わる: buffer_logical_path: String（エディタ以外の実行ではnil）。テキストサマリーは存在するとき(editor mode: lib/foo.rb) を末尾に追記する。JSON消費者はフィールドを直接見られる。

失敗エンベロープ

--tmp-file=Xが--instead-of=Yを伴わない、もしくは逆 → 終了コード 64、usage: --tmp-file and --instead-of must appear together。
--tmp-file=XでXが読み取り不可 → 終了コード1、読み込み失敗を説明するDiagnostic(path: '.rigor.yml', severity: :error)が1つ。
--instead-of=YのYがどのpaths:ディレクトリ配下にもない場合 → バッファの有効な論理同一性として扱われ、バッファは解析される。これは意図的である。エディタは時として、paths:に正式に属さないファイル（例: spec/がpaths:にない状態で解析されるspec/配下のファイル）に対してRigorを呼び出す。
バッファのパースエラーは今日のパースエラー診断として、path: lib/foo.rbで出力される。

v1スコープ外

マルチバッファ（--buffer A=B --buffer C=D）。
LSPデーモン、永続プロセス、ファイル監視。
ファイルごとの診断キャッシュ（ADR-17スライス3bの領分）。スコープ形状（B）のブロックを解除する。
プリパス再利用のためのプロジェクトコンテキストスナップショットキャッシュ。LSPパスについては着地済みである。Rigor::Analysis::ProjectScan ＋Runner#prepare_project_scan＋Runner.new(prebuilt:)（v0.1.6）として。LSPのProjectContextはスナップショットを遅延構築し、 DiagnosticPublisherは発行ごとのRunner.newそれぞれにそれをスレッディングする。CLI rigor check --tmp-fileはまだスナップショットを消費しない。各起動は新しいプロセスである。（プラグインマニフェストのダイジェスト、プロジェクトファイルのmtime + サイズリスト）をキーとするディスク裏付けのスナップショットキャッシュがあれば、ワンショット CLI起動でもプリパスをスキップできる。需要駆動。
呼び出し側が宣言した依存ファイル（--also=...）。（A）が出荷された後は些細なCLI拡張。エディタ拡張が実際に必要とするまで先送り。
rigor type-of境界でのキャッシング。type-ofのエディタモードは、既存の呼び出しごとのパスがすでに十分安価であるのと同程度に安価であるべきである。

スライス

BufferBinding値オブジェクト＋Runnerパラメータの配管。デフォルトnil。既存テストはグリーンのまま。
Runner#analyze_file／WorkerSession#analyzeがバインディングを尊重すること（パース＋診断出力）。単一ファイルエディタモードの統合 specがハッピーパスをカバーする。
Cache::Store::ReadOnlyラッパー＋CLIが--tmp-file下で自動的に有効化する。Spec: 空のキャッシュルートに対するバッファモード実行は後でもキャッシュルートを空のままにする。
rigor checkへのCLIフラグ＋使用法／エラーエンベロープ。Specはペア欠落／ファイル欠落のケースをカバーする。
単一ファイルスコープモード — --tmp-fileがセットされたとき、ランナーはバッファのみを解析する（オプションA）。他のファイルは Environmentコンテキストにのみ寄与する。プリパスはバッファ置き換えを伴って起動ごとに1回再実行される。Spec: Nファイルを持つプロジェクトに対するバッファモード実行はバッファに対してのみ診断を生成する。
rigor type-ofのエディタフラグ — 同じ--tmp-file／ --instead-ofの意味論。Spec: バッファ内(line, col)をホバーするとディスク上のファイルではなくバッファのバイトから導出された型を報告する。
Ractorプールが逐次に降格すること（エディタモード下）。CLIは警告を表示しない（オーバーライドは契約の一部であり、プール故障ではない）。 Spec: --workers=4 --tmp-file=...は逐次で動く。

スライス7のあとでv1の契約は完成する。キューイングされた項目（プロジェクトコンテキストスナップショットキャッシュ、ファイルごとの診断キャッシュ、--also、マルチバッファ）のスライスは、エディタモードを消費するエディタ拡張が具体的な必要を示したときに別途切られる。

オープンクエスチョン

エディタモード下のプラグイン信頼ポリシー。バッファファイルは許可された読み取りルートのいずれにも属さないかもしれない。今日のプラグインはPlugin::IoBoundaryを通じてI/Oポリシーを強制する。決定: 物理ファイルの読み込みはRigorのランナーが行い、プラグインは行わない。バッファのバイトはScopeレベルの状態を通じて流れ、 IoBoundary#read_fileを通らない。よって信頼ポリシーには影響しない。プラグインがバッファの論理パスを再度読み込む必要がある場合（稀 — rigor-actioncable／rigor-rails-i18nは読まない）、ディスク上のファイルを見ることになりバッファは見ない。これはv1の設計問題ではなく、文書化されたエッジケースである。
--cwd=PATHフラグを公開するかどうか。これによりエディタはプロジェクトルート外からRigorを実行できる。PHPStanは公開している。Rigor はConfiguration.discover経由で設定を解決する。エディタ拡張が作業ディレクトリの仮定が自分たちには合わないと報告するまで決定を先送りする。
--instead-ofがディスク上でパースエラーを持つファイルを指したときにどうするか（ディスク上のバージョンにエラーがあるがバッファでは修正されている場合）。今日のランナーはpaths:を展開し、ディスク上ファイルのパースエラーを含めてしまうだろう。決定: エディタモード下では論理パスのディスク上ファイルは丸ごとスキップされる。バッファのみがパースされる。