packages/interpreter - スクリプトインタプリタ

⚠️ このパッケージは非推奨です（2026-04-29 〜）。

現行の KSC 実行パスは packages/ksc-compiler（コンパイラ + IR + VM、Web/Native 共通）と packages/web/src/engine/{KscHostAdapter,EcsHostAdapter}.ts、packages/native-engine/src/engine/*HostBinding.{hpp,cpp} の組み合わせです。全体図は 22-ksc-pipeline-overview.md を参照。

詳細: packages/interpreter/DEPRECATED.md

概要

KSC (Kaede Script Code / .ksc) スクリプトの純 JavaScript インタプリタ。VM、デバッグモード（ブレークポイント、変数ウォッチ、トレースログ）、エラーハンドリング（Levenshtein 距離によるコマンド候補提示）を備える。

現状の利用先: packages/web/src/engine/_deprecated/WebEngine.ts のみ（既存利用先のためにビルド可能な状態は維持）。新規プロジェクトでは @kaedevn/ksc-compiler を使用してください。

ディレクトリ構成

packages/interpreter/
├── src/
│   ├── core/
│   │   ├── Interpreter.ts      # メインインタプリタ
│   │   ├── Parser.ts           # KSC パーサー
│   │   ├── Tokenizer.ts        # 字句解析
│   │   ├── Evaluator.ts        # 式評価
│   │   └── GameState.ts        # VM 状態管理
│   ├── engine/
│   │   ├── IEngineAPI.ts       # エンジンインターフェース
│   │   ├── ConsoleEngine.ts    # コンソール実装
│   │   └── TestEngine.ts       # テストハーネス
│   ├── debug/
│   │   ├── Debugger.ts         # ブレークポイント、変数ウォッチ
│   │   └── ErrorHandler.ts     # エラーレポート + コマンド候補
│   ├── types/
│   │   ├── Token.ts
│   │   ├── LineType.ts
│   │   ├── CallFrame.ts
│   │   ├── Choice.ts
│   │   └── Error.ts
│   └── index.ts                # 公開 API
├── test/                       # 15+ テストファイル
│   ├── Interpreter.test.ts
│   ├── Parser.test.ts
│   ├── Integration.test.ts
│   ├── Phase2-6.test.ts        # 多段階テスト
│   ├── ErrorHandling.test.ts
│   ├── Debug.test.ts
│   └── demo.ts
├── package.json
├── tsconfig.json
└── vitest.config.ts

主要ファイル

アーキテクチャ

[KSC スクリプト]
    ↓
[Tokenizer] → Token[]
    ↓
[Parser] → 行データ (テキスト/コマンド/制御フロー)
    ↓
[Interpreter]
    ├── [Evaluator] → 式評価
    ├── [GameState] → 状態管理
    ├── [Debugger] → デバッグ制御
    └── [IEngineAPI] → エンジン操作

IEngineAPI インターフェース

interface IEngineAPI {
  showText(speaker: string, body: string): Promise<void>;
  showChoice(options: Choice[]): Promise<number>;
  setBg(assetId: string): void;
  showCh(characterId: string, expressionId: string, position: string): void;
  hideCh(characterId: string): void;
  playBgm(assetId: string): void;
  playSe(assetId: string): void;
  wait(mode: string, ms?: number): Promise<void>;
}

実装

デバッグモード

• ブレークポイント: 行番号指定で実行停止
• 変数ウォッチ: 実行中の変数値をリアルタイム表示
• トレースログ: 実行された行をすべてログ出力
• ステップ実行: 1行ずつ実行

エラーハンドリング

• Levenshtein 距離: 不明なコマンドに対し、類似コマンドを候補提示
• スタックトレース: コールスタック付きエラーメッセージ
• エラーコンテキスト: エラー発生行の前後を表示

依存関係

• 内部: なし
• 外部: なし
• 被依存: なし（独立モジュール、将来的に web から参照予定）

テスト

• 107 テスト passing (Phase 7-3 時点)
• Interpreter.test.ts — 基本実行テスト
• Parser.test.ts — パース結果検証
• Integration.test.ts — 統合テスト
• ErrorHandling.test.ts — エラーケース
• Debug.test.ts — デバッグモード

既知の制限

• Phase 5 の再帰テスト（フィボナッチ）がハング
• 大規模ループテストがタイムアウト