vba-runner 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Koji Arai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ja.md

@@ -0,0 +1,94 @@
+# vba-runner
+
+Excel 不要で VBA コードを実行・テストできる TypeScript 実装の VBA 実行エンジンです。
+テストランナーとして使う場合は TypeScript からVBAファイルをロードして関数を呼び出せます。
+また、静的解析・整形・構文チェックの CLI ツールも同梱しています。
+
+## インストール
+
+```bash
+npm install vba-runner
+```
+
+## テストの書き方
+
+> [!TIP]
+> 実際にコードを書く前に、ブラウザ上で動作を確認したい場合は [Web UI デモサイト](https://vba-web-runner.netlify.app/) をご利用ください。`Debug.Print` の結果や構文チェックを即座に試すことができます。
+
+### 1. `eval`: VBAの式やコード断片をその場で評価する
+
+VBAの構文をそのまま文字列として渡し、評価結果を取得します。最も手軽にVBAエンジンを試すことができる方法です。
+
+```typescript
+import { VBARunner } from 'vba-runner';
+const vbaRunner = new VBARunner(); // 空の環境を作成
+
+// VBAの計算式を直接評価
+const sum = vbaRunner.eval("1 + 2 + 3"); // => 6
+
+// 変数宣言や代入を含む、複数行の処理も実行可能
+vbaRunner.eval("Dim x : x = 10 : Debug.Print x * 2");
+```
+
+### 2. `run`: ロードしたソース内の関数を実行する
+
+既存のVBAファイル（`.bas`）をロードし、そこに定義されたプロシージャを引数を指定して呼び出します。複雑なビジネスロジックのユニットテストに最適です。
+
+```typescript
+import { VBARunner, assert } from 'vba-runner';
+
+// 1. テスト対象のVBAファイルをロード
+const vbaRunner = new VBARunner('src/vba/Sample.bas');
+
+// 2. 関数名を指定して実行（第2引数はJavaScriptの配列として引数を渡す）
+const result1 = vbaRunner.run('Add', [1, 2]);
+const result2 = vbaRunner.run('Multiply', [result1, 2]);
+
+// 3. 結果をアサート
+assert.strictEqual(result1, 3);
+assert.strictEqual(result2, 6);
+```
+
+### 3. 複数ソースの一括ロード
+
+VBAファイル（`.bas`）を格納したディレクトリを指定すれば、配下のソースファイルをすべて読み込みます。
+規模の大きなVBAプロジェクトではこの使い方になります。
+
+```typescript
+import { VBARunner, assert } from 'vba-runner';
+
+// 1. テスト対象のVBAディレクトリをロード
+const vbaRunner = new VBARunner('src/vba');
+
+// 2. 関数名を指定して実行
+const result = vbaRunner.run('CalcTotal', [100, 200, 300]);
+assert.strictEqual(result, 600);
+```
+
+## CLI ツール
+
+`vba-runner` パッケージは以下の CLI ツールを提供します。
+
+| コマンド | 説明 |
+|---|---|
+| `vba-run <file.bas>` | VBAファイルを実行し、Debug.Print の出力を表示する |
+| `vba-analyzer <file.bas>` | VBAコードの静的解析（アウトライン・参照数・重複検出など） |
+| `vba-formatter <file.bas>` | VBAコードの整形（インデント・スペースの統一） |
+| `vba-parse-check <file.bas>` | VBAコードの構文チェック（パースエラーの検出） |
+
+```bash
+# VBAファイルの静的解析（アウトライン表示）
+vba-analyzer --outline src/vba/Module1.bas
+
+# 重複ブロックの検出
+vba-analyzer --diff src/vba/
+
+# 構文チェック
+vba-parse-check src/vba/Module1.bas
+```
+
+## 詳細ドキュメント
+
+- [REFERENCE.md](../../REFERENCE.md) — 型システム・モック登録・Sandbox方針・VFS など詳細仕様
+- [README.md](../../README.md) — プロジェクト概要・クイックスタート
+- [FOR_AI.md](../../FOR_AI.md) — AIによるリファクタリング支援ガイド

package/README.md

@@ -0,0 +1,91 @@
+# vba-runner
+
+A TypeScript-based VBA execution engine that runs and tests VBA code without Excel.
+Load `.bas` files from TypeScript and call VBA procedures directly, or use the bundled CLI tools for static analysis, formatting, and syntax checking.
+
+> 日本語ドキュメントは [README.ja.md](./README.ja.md) をご覧ください。
+
+## Installation
+
+```bash
+npm install vba-runner
+```
+
+## Usage
+
+> [!TIP]
+> Try it in the browser before writing any code: [Web UI Demo](https://vba-web-runner.netlify.app/) lets you run VBA snippets and check `Debug.Print` output instantly.
+
+### 1. `eval`: Evaluate a VBA expression or code fragment inline
+
+Pass VBA syntax as a string and get the result back. The quickest way to try the engine.
+
+```typescript
+import { VBARunner } from 'vba-runner';
+const vbaRunner = new VBARunner(); // create an empty environment
+
+// Evaluate a VBA expression directly
+const sum = vbaRunner.eval("1 + 2 + 3"); // => 6
+
+// Multi-line code with variable declarations works too
+vbaRunner.eval("Dim x : x = 10 : Debug.Print x * 2");
+```
+
+### 2. `run`: Call a procedure defined in a loaded VBA file
+
+Load an existing `.bas` file and call its procedures with arguments. Ideal for unit-testing complex business logic.
+
+```typescript
+import { VBARunner, assert } from 'vba-runner';
+
+// 1. Load the VBA file under test
+const vbaRunner = new VBARunner('src/vba/Sample.bas');
+
+// 2. Call a procedure by name (pass arguments as a JavaScript array)
+const result1 = vbaRunner.run('Add', [1, 2]);
+const result2 = vbaRunner.run('Multiply', [result1, 2]);
+
+// 3. Assert the results
+assert.strictEqual(result1, 3);
+assert.strictEqual(result2, 6);
+```
+
+### 3. Load an entire directory
+
+Point `VBARunner` at a directory to load all `.bas` files at once. Use this for larger VBA projects with multiple modules.
+
+```typescript
+import { VBARunner, assert } from 'vba-runner';
+
+// 1. Load all VBA files in the directory
+const vbaRunner = new VBARunner('src/vba');
+
+// 2. Call any procedure defined across those files
+const result = vbaRunner.run('CalcTotal', [100, 200, 300]);
+assert.strictEqual(result, 600);
+```
+
+## CLI Tools
+
+| Command | Description |
+|---|---|
+| `vba-run <file.bas>` | Execute a VBA file and print `Debug.Print` output |
+| `vba-analyzer <file.bas>` | Static analysis: outline, reference counts, duplicate detection |
+| `vba-formatter <file.bas>` | Format VBA code (indentation, spacing) |
+| `vba-parse-check <file.bas>` | Syntax check (detect parse errors) |
+
+```bash
+# Show outline of a VBA file
+vba-analyzer --outline src/vba/Module1.bas
+
+# Detect duplicate code blocks
+vba-analyzer --diff src/vba/
+
+# Syntax check
+vba-parse-check src/vba/Module1.bas
+```
+
+## Documentation
+
+- [REFERENCE.md](https://github.com/jca02266/vba-runner/blob/main/REFERENCE.md) — Type system, mock registration, Sandbox policy, VFS details
+- [README.md](https://github.com/jca02266/vba-runner/blob/main/README.md) — Project overview and quick start