Issue #142: @ruby/prism 移行ノート

[takaokouji]

Issue #142: @ruby/prism 移行ノート

概要

スモウルビーの Ruby → ブロック変換パーサーを、Opal + whitequark/parser から @ruby/prism JavaScript バインディングに移行した。

背景・動機

• whitequark/parser は Ruby 3.3 以下のみ対応。Ruby 3.4 以降は非推奨
• Opal はビルドサイズが大きく（opal.min.js + opal-parser.min.js で ~3MB）、メンテナンスコストが高い
• Prism は Ruby 3.4 の公式パーサーであり、JavaScript バインディング (@ruby/prism) が提供されている

移行方針

1. packages/scratch-gui/src/lib/ruby-parser.js を Prism の薄いラッパーに置き換え
2. packages/scratch-gui/src/lib/prism-parser.js を新規作成（WASM ローダー）
3. packages/scratch-gui/src/lib/ruby-to-blocks-converter/ を Visitor パターンで再実装
4. Opal 関連ファイルを全て削除

主な変更ファイル

ファイル	変更内容
src/lib/prism-parser.js	新規作成。WASM をロードし parse() を提供
src/lib/ruby-parser.js	prism-parser への薄いラッパーに置き換え
src/lib/ruby-to-blocks-converter/index.js	process() を async に変更、Prism parse を使用
src/lib/ruby-to-blocks-converter/ast-handlers/core.js	visitProgramNode, visitStatementsNode など
src/lib/ruby-to-blocks-converter/ast-handlers/expressions.js	visitCallNode など全式ノード
src/lib/ruby-to-blocks-converter/ast-handlers/control-flow.js	visitIfNode, visitUnlessNode, visitDefNode など
src/lib/ruby-to-blocks-converter/ast-handlers/assignments.js	各種代入ノード
webpack.config.js	prism.wasm を asset/inline で埋め込み、Opal 関連を削除
package.json	opal-loader 削除、setup:opal スクリプト削除

Opal/whitequark → Prism の AST ノード名対応表

Opal/whitequark ノード	Prism ノード	備考
send (node type string)	CallNode	メソッド呼び出し
args / argument list	ArgumentsNode (.arguments_)	JS予約語 arguments を避けて arguments_
lvasgn	LocalVariableWriteNode	ローカル変数代入
ivasgn	InstanceVariableWriteNode	インスタンス変数代入
gvasgn	GlobalVariableWriteNode	グローバル変数代入
lvar	LocalVariableReadNode	ローカル変数参照
ivar	InstanceVariableReadNode	インスタンス変数参照（.name は @foo 形式）
gvar	GlobalVariableReadNode	グローバル変数参照（.name は $foo 形式）
op-asgn	LocalVariableOperatorWriteNode 等	+= 等の複合代入
if	IfNode	if/unless 条件分岐
unless	UnlessNode	unless → branches を入れ替えて control_if_else に変換
block	BlockNode (.body, .parameters)	do...end / {} ブロック
str	StringNode (.unescaped.value)	文字列
sym	SymbolNode (.unescaped.value)	シンボル
int	IntegerNode (.value)	整数
float	FloatNode (.value)	浮動小数点
true / false	TrueNode / FalseNode	真偽値
nil	NilNode	nil
self	SelfNode	self
const	ConstantReadNode (.name)	定数（単体）
const with scope	ConstantPathNode (.name, .parent)	スコープ付き定数
hash	HashNode (.elements → AssocNode 配列)	ハッシュリテラル
keyword args	KeywordHashNode	キーワード引数（foo(secs: 5) 等）
array	ArrayNode (.elements)	配列リテラル
begin / kwbegin	BeginNode / StatementsNode	ブロック本体
def	DefNode (.name, .parameters, .body)	メソッド定義
return	ReturnNode (.arguments_)	return 文
range (inclusive)	RangeNode (.isExcludeEnd() === false)	1..10
range (exclusive)	RangeNode (.isExcludeEnd() === true)	1...10

移行で問題となった箇所

1. arguments_ プロパティ名

Prism JS バインディングでは arguments が JavaScript 予約語であるため、ArgumentsNode には .arguments_ でアクセスする。

// Prism
const args = (node.arguments_ ? node.arguments_.arguments_ : [])

2. WASM のロード方法

prism.wasm のロード戦略はビルド種別によって異なる：

ビルド	webpack ルール	ロード方法
統合テスト（file://）/ 開発サーバー	asset/inline → data: URL	atob() デコード → compile + instantiate
production（BUILD_TYPE=dist-html、https://smalruby.app）	asset/resource → https: URL	WebAssembly.instantiateStreaming(fetch(url))

• asset/inline は prism.wasm を Base64 でバンドルに埋め込む。file:// では fetch() が CORS エラーになるため必要。
• asset/resource は別ファイルとして配信。production では fetch() が使えるので instantiateStreaming() でストリーミングコンパイル可能（バンドルサイズ削減・ブラウザキャッシュも効く）。

// webpack.config.js: dist-html のみ asset/resource にオーバーライド
const wasmRule = config.module.rules.find(r => r.test && r.test.toString() === '/prism\\.wasm$/');
if (wasmRule) {
    wasmRule.type = 'asset/resource';
}

// prism-parser.js
const prismWasmUrl = (await import('@ruby/prism/src/prism.wasm')).default;
if (typeof prismWasmUrl === 'string' && prismWasmUrl.startsWith('data:')) {
    // data: URL (file:// 環境) → atob() でデコードして compile + instantiate
    const wasm = await WebAssembly.compile(bytes.buffer);
    instance = await WebAssembly.instantiate(wasm, importObject);
} else {
    // 通常 URL (production / dev server) → instantiateStreaming()
    ({instance} = await WebAssembly.instantiateStreaming(fetch(prismWasmUrl), importObject));
}

3. InstanceVariableReadNode の .name に @ が含まれる

Prism では @foo の .name は "@foo"（@ を含む）。variable-utils.js の _lookupOrCreateVariableOrList で先頭文字チェックで対応済み：

if (name[0] === '@') {
    varName = name.slice(1);  // @を除去
    scope = 'instance';
}

4. SymbolNode のキー（HashNode）

Prism の HashNode ではキーが SymbolNode として渡される。Primitive クラスの _hashCache で sym:keyName 形式の文字列キーに変換してキャッシュ：

this._hashCache.set(`sym:${k.value}`, v);
// 使用側: hash.get('sym:secs')

5. UnlessNode のブランチ順序

Prism の UnlessNode は { predicate, statements (then), elseClause } の構造。
Scratch の control_if_else は { CONDITION, SUBSTACK (then), SUBSTACK2 (else) } の順。
unless cond; A; else; B; end は「condが偽のときA、真のときB」なので、
branches を入れ替えて control_if_else(cond, branch1=B, branch2=A) に変換する：

visitUnlessNode(node) {
    // branches[0] = else節（if-thenに相当）、branches[1] = unless節（if-elseに相当）
    return this._createIfElseBlock(node.predicate, elseBlock, thenBlock);
}

6. CallNode の receiver が null の場合

Prism では say("Hello!") のようにレシーバーなしのメソッド呼び出しの .receiver は null。
_getReceiverName(null) → 'sprite'（またはステージの場合 'stage'）として処理する。

7. DefNode の parameters

Prism の DefNode.parameters は ParametersNode（Opal では引数リストが直接配列だった）。
visitParametersNode で requireds 配列を返すことで対応：

visitParametersNode(node) {
    return node.requireds || [];
}

今後の不具合対応のポイント

1. 新しいメソッド呼び出しパターン: 新しい Ruby 構文を追加する場合、対応する Visitor メソッド（visitXxxNode）が index.js の visit から呼ばれるか確認
2. ノード型の確認: node.constructor.name で型を判定する箇所が多い。Prism の AST が変わった場合に影響あり
3. arguments_ のアクセス: 全ての引数アクセスは node.arguments_.arguments_ の形式（ダブルアンダースコア）
4. SymbolNode のキー: ハッシュの symbol キーは sym:keyName 形式でキャッシュされる
5. UnlessNode: visitUnlessNode は branches を入れ替える特殊な変換が必要

テスト構成

• Unit tests: test/unit/lib/ruby-to-blocks-converter/ 以下（Prism WASM のモックあり）
• Integration tests: test/integration/ruby-tab/ 以下（実際のブラウザで変換をテスト）
• Unit test setup: test/unit/lib/setup-prism.js（Node.js 環境での WASM ロード）

削除したもの

• packages/scratch-gui/opal/ ディレクトリ全体
• packages/scratch-gui/scripts/make-setup-opal.js
• packages/scratch-gui/static/javascripts/setup-opal.js
• packages/scratch-gui/test/setup-opal.js
• package.json: setup:opal スクリプト、prebuild フック、opal-loader 依存関係、Jest の opal/opal-parser エイリアス
• webpack.config.js: opal エイリアス、.rb ファイルの opal-loader ルール
• src/playground/index.ejs: setup-opal.js の <script> タグ
• src/lib/log-suppression.js: Opal 警告メッセージの抑制