アーキテクチャの概要

Vize の JavaScript パッケージと Rust のコンパイラ・開発ツールのつながりを説明します。 連携の不具合を調べたり修正を提案したりする前に、どの部分が動作を担当するか確認したいときに使ってください。 アプリへの導入は Getting Started から始められます。

関係図 で、@vizejs/vite-plugin などの入口から担当クレートをたどってください。 実装ファイルは ソースガイド、公開 API の役割は クレートリファレンス で確認できます。

図は crates/ にある既存製品の処理経路を表しています。実験段階のレベル構造は davinci/ にあり、 移行の順序と条件は レベル再編の決定記録 に記載されています。 内部構造は引き続き変更されます。

プロジェクト関係マップ

JavaScript の連携パッケージはネイティブバインディングを呼び出し、コンパイラと開発ツールは 共通の構文解析・意味解析を利用します。利用しているパッケージから矢印をたどってください。

この図は、各機能の担当と共通基盤の利用関係を示しており、すべての呼び出し経路を表すものではありません。 パーサー、AST、意味解析を共有し、その共通の言語モデルを中心に、コンパイラのバックエンドや開発ツールを 置き換えられる構造にすることが基本方針です。

コンパイルの流れ

各段階の役割

1. ソース — <template>、<script>、<style> ブロックを含む .vue ファイルです。
2. Armature（パーサー） — ソースをトークン列に分け、構造化した AST に解析します。字句解析では、ディレクティブ (v-if、v-for、v-bind)、式の補間 ({{ }})、SFC ブロックの境界など、Vue 固有の構文を扱います。
3. Relief（AST） — 後続の段階が利用する共通の中間表現です。構文木を共有して、同じ構文の解析を重複させないようにします。
4. Croquis（意味解析） — テンプレートの式の解決、変数スコープの追跡、バインディングの種類（setup・data・props・inject）の検出、式の妥当性の確認を行います。JavaScript・TypeScript の AST の解析には OXC を使います。
5. Atelier（コンパイル） — 解析済みの AST を JavaScript に変換します。出力先に応じて、次の三つのバックエンドを使います。
   • VDOM (vize_atelier_dom) — パッチフラグによる最適化や静的な要素の巻き上げを使い、createVNode・h の呼び出しを生成します。
   • Vapor (vize_atelier_vapor) — VDOM を使わず、DOM を直接操作する細粒度のリアクティブコードを生成します。
   • SSR (vize_atelier_ssr) — ハイドレーション用のマーカーを含む、文字列を連結するコードを生成します。
6. 出力 — ソースマップを含む JavaScript コードです。

開発ツールの流れ

コンパイルに加えて、同じ構文解析・意味解析の基盤を利用する開発ツールがあります。

構文解析と AST の共通化により、言語処理の重複を減らせます。コンパイラや各ツールの互換性は、 それぞれのフィクスチャと連携テストで確認します。

型チェックでは、vize_canon が Vue SFC から仮想 TypeScript を生成します。 corsa-bind を通じて Corsa のプロジェクトセッションにネイティブ診断を依頼し、 結果を元のファイルの位置に対応付けます。

実装を変更する際に必要な検証は、言語工学の実践 にまとめています。 パーサー、コンパイラ、解析器、型チェッカー、フォーマッタ、LSP、リリースの変更に対して、 フィクスチャ、スナップショット、互換性、ベンチマーク、利用準備状況をどう確認するかが分かります。

クレートの役割

Musea のギャラリー UI と開発サーバーとの連携は、JavaScript パッケージの @vizejs/vite-plugin-musea が担当します。Rust クレートは解析と生成の中核処理を担当します。

命名規則

既存製品のクレート名は、美術や彫刻の用語に由来します。それぞれが Vue のコードを整形・変換する役割に対応し、 クレート同士の関係を表しています。名前の考え方は Philosophy を参照してください。

名前から役割を読む

コンパイルの役割と美術の制作工程は、次のように対応しています。

• パーサー（Armature） は内部の骨組みです。彫刻の芯材が粘土を支えるように、後続の処理が使う構造を作ります。
• 意味解析（Croquis） は素早い下描きです。最終的な形にする前に、コードの本質的な意味を捉えます。
• コンパイラ（Atelier） は工房です。素材を完成した作品へ変換します。
• AST（Relief） は立体的な表現です。平面の文字列に構造を与えます。
• バインディング（Vitrine） はガラス展示ケースです。中の実装を直接変更せず、外から結果を見たり操作したりできます。
• リンター（Patina） は表面の仕上がりを調べます。全体の品質に影響する問題を見つけます。
• フォーマッタ（Glyph） は比例を揃えます。文字の間隔を整えて彫るように、コードの形を統一します。

たとえば vize_atelier_dom は、VDOM 向けの出力 を生成する 工房 に当たるクレートです。 名前の由来に加えて、担当する機能は クレートリファレンス でも確認できます。

外部依存関係

専門的な処理には、Rust エコシステムのライブラリなどを利用します。