# Architecture Decision Records (ADR)

**Project**: Excel2Spec
**Last Updated**: 2025-12-12

---

## ADR-001: プログラミング言語の選択

### ステータス
**Accepted** (2025-12-12)

### コンテキスト
Excel2Specは、Excel VBAファイルを解析し仕様書を生成するCLIツールです。
以下の言語が候補として検討されました：
- Python
- Node.js / TypeScript
- Rust
- C# / .NET

### 決定
**Python 3.11+** を採用する。

### 理由
1. **ライブラリエコシステム**: xlrd, openpyxl, oletoolsなど、Excel/VBA処理に成熟したライブラリが豊富
2. **開発速度**: 動的型付け言語で迅速なプロトタイピングが可能
3. **クロスプラットフォーム**: Windows/macOS/Linuxで同一コードが動作
4. **AI統合**: 将来的なLLM統合（OpenAI SDK等）が容易
5. **型ヒント**: Python 3.11+の型ヒントでmypyによる静的解析が可能

### 代替案
- **Node.js**: VBA解析ライブラリが限定的
- **Rust**: 開発速度よりも実行速度を優先する段階ではない
- **C#**: OLEオートメーションは強力だが、Linux/macOS対応が複雑

### 影響
- 実行にはPython 3.11+のインストールが必要
- 将来的にPyInstallerで単一バイナリ化可能

---

## ADR-002: VBA抽出ライブラリの選択

### ステータス
**Accepted** (2025-12-12)

### コンテキスト
ExcelファイルからVBAコードを抽出する方法が必要です。
候補：
- oletools (olevba)
- win32com (Windows専用)
- 独自実装（OLE構造解析）

### 決定
**oletools** を採用する。

### 理由
1. **クロスプラットフォーム**: Windows以外でも動作
2. **成熟度**: セキュリティ分析用途で広く使用されている
3. **xlsとxlsm両対応**: 古い形式と新しい形式の両方をサポート
4. **パスワード保護検出**: 保護されたVBAプロジェクトを検出可能

### 代替案
- **win32com**: Windowsのみで動作、Excel本体が必要
- **独自実装**: 開発工数が大きい

### 影響
- oletoolsの依存関係が追加される
- 一部のエッジケース（暗号化ブック等）では抽出できない可能性

---

## ADR-003: CLIフレームワークの選択

### ステータス
**Accepted** (2025-12-12)

### コンテキスト
CLIインターフェースを構築するためのフレームワークが必要です。
候補：
- argparse (標準ライブラリ)
- Click
- Typer

### 決定
**Typer** を採用する。

### 理由
1. **型ヒント統合**: 関数の型ヒントからCLI引数を自動生成
2. **自動ヘルプ**: --helpの自動生成
3. **Rich統合**: カラフルな出力が標準で利用可能
4. **Clickベース**: Clickの安定性を継承

### 代替案
- **argparse**: ボイラープレートが多い
- **Click**: Typerの方が型ヒントとの統合が良い

### 影響
- typerとrichが依存関係に追加される

---

## ADR-004: アーキテクチャパターンの選択

### ステータス
**Accepted** (2025-12-12)

### コンテキスト
コードの構造化とテスタビリティを確保するためのアーキテクチャパターンが必要です。

### 決定
**Clean Architecture（クリーンアーキテクチャ）** を採用する。

4層構造：
1. Domain層（ビジネスモデル）
2. Application層（ユースケース）
3. Infrastructure層（外部統合）
4. Presentation層（CLI/出力）

### 理由
1. **テスタビリティ**: 各層を独立してテスト可能
2. **依存性逆転**: Infrastructure層をモック可能
3. **保守性**: 関心の分離が明確
4. **拡張性**: 新しい出力形式やリーダーを追加しやすい

### 代替案
- **シンプルなスクリプト**: 小規模プロジェクトでは過剰設計になる可能性
- **MVC**: CLI向けではない

### 影響
- 初期の学習コストが若干高い
- ファイル数が増加する

---

## ADR-005: VBA構文解析の方法

### ステータス
**Accepted** (2025-12-12)

### コンテキスト
VBAソースコードを解析し、プロシージャや変数を抽出する方法が必要です。
候補：
- 正規表現ベースのパーサー
- ANTLR4によるVBA文法定義
- 既存のVBAパーサーライブラリ

### 決定
**正規表現ベースのカスタムパーサー** を採用する（MVP）。
将来的にANTLR4への移行を検討。

### 理由
1. **開発速度**: 正規表現で迅速に実装可能
2. **依存関係**: 追加のパーサージェネレータが不要
3. **MVP優先**: 完璧な解析より動作するMVPを優先
4. **80/20ルール**: 80%のケースを正規表現でカバー可能

### 代替案
- **ANTLR4**: 完全なVBA文法をサポートできるが、開発工数が大きい
- **既存ライブラリ**: Python向けの成熟したVBAパーサーが存在しない

### 影響
- 複雑なVBA構文（行継続、コメント内のキーワード等）で誤検出の可能性
- 将来的なリファクタリングの技術的負債

### マイグレーションパス
Phase 3でANTLR4ベースのパーサーに移行検討：
```
Phase 1 (MVP): 正規表現パーサー
Phase 3: ANTLR4パーサー（オプション）
```

---

## ADR-006: 出力形式の設計

### ステータス
**Accepted** (2025-12-12)

### コンテキスト
生成する仕様書の形式を決定する必要があります。

### 決定
以下の形式をサポートする：
1. **Markdown** (デフォルト) - MVP
2. **JSON** - MVP
3. **HTML** - Phase 2

### 理由
1. **Markdown**: GitHubでの表示、他ツールへの変換が容易
2. **JSON**: プログラムによる後処理が可能
3. **HTML**: ブラウザで直接閲覧可能

### 出力構造（Markdown）
```markdown
# {filename} 仕様書

**生成日時**: YYYY-MM-DD HH:MM:SS

## シート一覧
- Sheet1
- Sheet2

## VBAモジュール一覧

| モジュール名 | 種別 | プロシージャ数 |
|-------------|------|--------------|
| Module1 | standard | 3 |

### Module1

**種別**: standard

#### プロシージャ一覧

##### CalculateTotal

- **種別**: function
- **アクセス**: Public
- **引数**: startRow: Long, endRow: Long
- **戻り値**: Double
```

---

## ADR-007: エラーハンドリング戦略

### ステータス
**Accepted** (2025-12-12)

### コンテキスト
エラー発生時の動作を決定する必要があります。

### 決定
**Graceful Degradation（優雅な劣化）** 戦略を採用する。

### 原則
1. **致命的エラー**: ファイルが存在しない、形式がサポート外 → 即座に終了
2. **部分的エラー**: VBA保護、一部モジュールの解析失敗 → 警告を出して続行
3. **詳細ログ**: --verbose オプションで詳細なエラー情報を出力

### 終了コード
| コード | 意味 |
|-------|------|
| 0 | 成功 |
| 1 | ファイルエラー（存在しない、読み込み不可） |
| 2 | 形式エラー（サポート外の形式） |
| 3 | 部分的エラー（一部の解析に失敗したが出力は生成） |

### 影響
- ユーザーは部分的な結果でも利用可能
- CI/CDでの利用時は終了コードで判断可能

---

## ADR-008: テスト戦略

### ステータス
**Accepted** (2025-12-12)

### コンテキスト
テストの方針と構造を決定する必要があります。

### 決定
以下のテスト戦略を採用する：

1. **単体テスト**: pytest
   - Domain層: 100%カバレッジ目標
   - Infrastructure層: 80%カバレッジ目標

2. **統合テスト**: 実際のExcelファイルを使用
   - tests/fixtures/ にサンプルファイルを配置

3. **E2Eテスト**: CLIコマンドの実行テスト

### テストピラミッド
```
       /\
      /  \  E2E (少数)
     /----\
    /      \ 統合テスト (中程度)
   /--------\
  /          \ 単体テスト (多数)
 /------------\
```

### フィクスチャファイル
```
tests/fixtures/
├── simple.xls        # シンプルなVBA付きxls
├── simple.xlsm       # シンプルなVBA付きxlsm
├── no_vba.xlsx       # VBAなしxlsx
├── protected_vba.xlsm # VBA保護付き
├── japanese.xlsm     # 日本語VBA
└── complex.xlsm      # 複雑なVBA（複数モジュール）
```

---

## ADR-009: 日本語対応

### ステータス
**Accepted** (2025-12-12)

### コンテキスト
日本語を含むVBAコードとExcelファイルのサポートが必要です。

### 決定
以下の方針で日本語をサポートする：

1. **入力**: Shift_JIS（xls）、UTF-8（xlsm）を自動判定
2. **出力**: UTF-8で統一
3. **エラーメッセージ**: 日本語
4. **ログ**: 日本語

### 影響
- 一部の古いxlsファイルでエンコーディング問題が発生する可能性
- chardetライブラリの追加を検討（必要に応じて）

---

## ADR索引

| ADR | タイトル | ステータス |
|-----|---------|-----------|
| ADR-001 | プログラミング言語の選択 | Accepted |
| ADR-002 | VBA抽出ライブラリの選択 | Accepted |
| ADR-003 | CLIフレームワークの選択 | Accepted |
| ADR-004 | アーキテクチャパターンの選択 | Accepted |
| ADR-005 | VBA構文解析の方法 | Accepted |
| ADR-006 | 出力形式の設計 | Accepted |
| ADR-007 | エラーハンドリング戦略 | Accepted |
| ADR-008 | テスト戦略 | Accepted |
| ADR-009 | 日本語対応 | Accepted |

---

**Last Updated**: 2025-12-12
**Author**: MUSUBI SDD Workflow
