rbcsv 0.1.6 → 0.1.8

data/DEVELOPMENT.md

@@ -1,24 +1,32 @@
-# 開発ガイド
+# RbCsv 開発ガイド
 
-このドキュメントでは、rbcsvの開発環境のセットアップ、ビルド方法、リリース手順について説明します。
+このドキュメントでは、rbcsvの開発環境のセットアップ、ビルド方法、テスト手順、リリース手順について詳しく説明します。
 
 ## 必要な環境
 
-- Ruby 3.0以降
-- Rust（最新の安定版を推奨）
-- Bundler gem
-- Git
+- **Ruby**: 3.2.0以降（gemspec要件）
+- **Rust**: 最新の安定版を推奨（MSRV: 1.75+）
+- **Bundler**: gem管理
+- **Git**: バージョン管理
+- **RubyGems**: 3.3.11以降
+
+### システム要件
+
+- **macOS**: Apple Silicon (arm64) / Intel (x86_64)
+- **Linux**: x86_64 / aarch64
+- **Windows**: x86_64（実験的サポート）
+
 
 ## 開発環境のセットアップ
 
 ### 1. リポジトリのクローン
 
 ```bash
-git clone <repository-url>
-cd r_csv
+git clone https://github.com/fs0414/rbcsv.git
+cd rbcsv
 ```
 
-### 2. 依存関係のインストール
+### 2. Ruby依存関係のインストール
 
 ```bash
 bundle install
@@ -27,221 +35,551 @@ bundle install
 ### 3. ネイティブ拡張のビルド
 
 ```bash
+# 推奨方法（rb_sys使用）
 rake compile
+
+# 代替方法（開発時）
+bundle exec rake compile
+```
+
+### 4. 動作確認
+
+#### CSV パース機能
+
+```bash
+# 基本的なパース
+ruby -I lib -e "require 'rbcsv'; p RbCsv.parse('a,b\n1,2')"
+# 期待される出力: [["a", "b"], ["1", "2"]]
+
+# trim機能付きパース
+ruby -I lib -e "require 'rbcsv'; p RbCsv.parse!(' a , b \n 1 , 2 ')"
+# 期待される出力: [["a", "b"], ["1", "2"]]
+```
+
+#### CSV ファイル読み込み機能
+
+```bash
+# CSVファイル読み込み
+ruby -I lib -e "require 'rbcsv'; p RbCsv.read('spec/fixtures/test.csv')"
+# 期待される出力: [["name", "age", "city"], ["Alice", "25", "Tokyo"], ...]
+
+# trim機能付きファイル読み込み
+ruby -I lib -e "require 'rbcsv'; p RbCsv.read!('spec/fixtures/test_with_spaces.csv')"
+# 期待される出力: [["name", "age", "city"], ["Alice", "25", "Tokyo"], ...]
+```
+
+#### CSV ファイル書き込み機能
+
+```bash
+# 基本的なファイル書き込み
+ruby -I lib -e "
+require 'rbcsv'
+data = [['name', 'age', 'city'], ['Alice', '25', 'Tokyo'], ['Bob', '30', 'Osaka']]
+RbCsv.write('/tmp/test_output.csv', data)
+puts 'File written successfully!'
+puts File.read('/tmp/test_output.csv')
+"
+# 期待される出力:
+# File written successfully!
+# name,age,city
+# Alice,25,Tokyo
+# Bob,30,Osaka
+
+# 書き込み→読み込みの往復テスト
+ruby -I lib -e "
+require 'rbcsv'
+data = [['product', 'price'], ['Apple', '100'], ['Orange', '80']]
+RbCsv.write('/tmp/roundtrip.csv', data)
+result = RbCsv.read('/tmp/roundtrip.csv')
+puts 'Original data:'
+p data
+puts 'Read back data:'
+p result
+puts 'Match: #{data == result}'
+"
+# 期待される出力: Match: true
+
+# エラーハンドリングテスト（空データ）
+ruby -I lib -e "
+require 'rbcsv'
+begin
+  RbCsv.write('/tmp/empty.csv', [])
+rescue => e
+  puts 'Error caught: #{e.message}'
+end
+"
+# 期待される出力: Error caught: Invalid Data Error: CSV data is empty
+
+# エラーハンドリングテスト（フィールド数不一致）
+ruby -I lib -e "
+require 'rbcsv'
+begin
+  data = [['name', 'age'], ['Alice', '25', 'Tokyo']]
+  RbCsv.write('/tmp/mismatch.csv', data)
+rescue => e
+  puts 'Error caught: #{e.message}'
+end
+"
+# 期待される出力: Error caught: Invalid Data Error: Field count mismatch at line 2: expected 2 fields, got 3 fields
+
+# ファイル上書きテスト
+ruby -I lib -e "
+require 'rbcsv'
+# 最初のデータを書き込み
+RbCsv.write('/tmp/overwrite_test.csv', [['old'], ['data']])
+puts 'First write:'
+puts File.read('/tmp/overwrite_test.csv')
+
+# 新しいデータで上書き
+RbCsv.write('/tmp/overwrite_test.csv', [['new', 'data'], ['updated', 'content']])
+puts 'After overwrite:'
+puts File.read('/tmp/overwrite_test.csv')
+"
+# 期待される出力: 最初にold,dataが出力され、その後new,data形式に変わる
+```
+
+## ビルドプロセス
+
+### 自動ビルド（推奨）
+
+```bash
+# 全体ビルド（コンパイル、テスト、リント）
+rake
+
+# 拡張のみコンパイル
+rake compile
+
+# クリーンビルド
+rake clean
+rake compile
+```
+
+### 手動ビルド手順
+
+```bash
+# 1. 前回のビルドをクリーン
+rm -rf lib/rbcsv/rbcsv.bundle tmp/ target/
+
+# 2. Rust拡張のコンパイル
+cd ext/rbcsv
+cargo build --release
+cd ../..
+
+# 3. バンドルファイルのコピー（macOSの場合）
+cp target/release/librbcsv.dylib lib/rbcsv/rbcsv.bundle
+
+# Linuxの場合
+# cp target/release/librbcsv.so lib/rbcsv/rbcsv.bundle
+```
+
+### ビルドのトラブルシューティング
+
+#### ABIバージョンの不一致
+
+```bash
+# エラー例: "incompatible ABI version"
+rm -rf lib/rbcsv/rbcsv.bundle tmp/ target/
+bundle exec rake compile
 ```
 
-### 4. テストの実行
+#### Rust/Cargoの問題
 
-#### Rubyテスト
 ```bash
+# Rust依存関係の更新
+cd ext/rbcsv
+cargo update
+cargo clean
+cargo build --release
+cd ../..
+```
+
+#### Magnus APIエラー
+
+```bash
+# 最新のMagnus 0.8.1では、ReprValueトレイトの明示的インポートが必要
+# ruby_api.rs で以下が含まれていることを確認:
+use magnus::{value::ReprValue};
+```
+
+## テスト手順
+
+### Ruby統合テスト
+
+```bash
+# 全テスト実行
 bundle exec rspec
+
+# 特定のテストファイル
+bundle exec rspec spec/rbcsv_spec.rb
+
+# 詳細出力
+bundle exec rspec --format documentation
 ```
 
-#### Rustテスト
+### Rustユニットテスト
+
 ```bash
+# 全Rustテスト
 cd ext/rbcsv
 cargo test
+
+# 詳細出力
+cargo test -- --nocapture
+
+# 特定のテスト
+cargo test test_parse_basic
 cd ../..
 ```
 
-### 5. 動作確認テスト
+### パフォーマンステスト
 
 ```bash
-ruby -I lib -e "require 'rbcsv'; p RbCsv.parse('a,b\n1,2')"
+# ベンチマーク実行
+ruby benchmark.rb
+
+# カスタムテストファイルでのテスト
+ruby test.rb
 ```
 
-期待される出力: `[["a", "b"], ["1", "2"]]`
+### コードスタイルチェック
 
-## プロジェクト構成
+```bash
+# Rubyコード（RuboCop）
+bundle exec rubocop
 
+# Rustコード
+cd ext/rbcsv
+cargo fmt --check
+cargo clippy -- -D warnings
+cd ../..
 ```
-r_csv/
-├── lib/
-│   ├── rbcsv.rb              # メインのRubyモジュール
-│   └── rbcsv/
-│       ├── version.rb        # バージョン定義
-│       └── rbcsv.bundle      # コンパイル済みネイティブ拡張
-├── ext/
-│   └── rbcsv/
-│       ├── src/
-│       │   └── lib.rs        # Rust実装
-│       ├── Cargo.toml        # Rust依存関係
-│       └── extconf.rb        # Ruby拡張の設定
-├── spec/                     # Rubyテスト
-├── rbcsv.gemspec            # Gem仕様
-├── Rakefile                 # ビルドタスク
-└── DEVELOPMENT.md           # このファイル
+
+## API設計
+
+### 現在のAPI（v0.1.7+）
+
+```ruby
+# 関数ベースAPI（`!`サフィックスでtrim機能分離）
+RbCsv.parse(csv_string)          # 通常のパース
+RbCsv.parse!(csv_string)         # trim機能付きパース
+RbCsv.read(file_path)            # 通常のファイル読み込み
+RbCsv.read!(file_path)           # trim機能付きファイル読み込み
+RbCsv.write(file_path, data)     # CSVファイル書き込み
+
+# データ形式
+data = [
+  ["header1", "header2", "header3"],  # ヘッダー行
+  ["value1", "value2", "value3"],     # データ行
+  # ...
+]
 ```
 
-## ビルドプロセス
+### API進化の履歴
 
-このプロジェクトは、`rb_sys`クレートとRubyの拡張メカニズムを通じてコンパイルされるRustベースのネイティブ拡張を使用しています。
+#### v0.1.6以前（オプションベース）
+```ruby
+RbCsv.parse(csv_string, {trim: true})
+RbCsv.read(file_path, {trim: false})
+```
 
-### 手動ビルド手順
+#### v0.1.7+（関数ベース）
+```ruby
+RbCsv.parse!(csv_string)  # trim版
+RbCsv.write(file_path, data)  # 新機能
+```
 
-1. **前回のビルドをクリーン**（必要に応じて）:
-   ```bash
-   rm -rf lib/rbcsv/rbcsv.bundle tmp/
-   ```
+### 実装アーキテクチャ
 
-2. **拡張のコンパイル**:
-   ```bash
-   rake compile
-   ```
+1. **parser.rs**: CSV解析・書き込みコア機能、エラーハンドリング
+2. **ruby_api.rs**: Ruby API関数、Magnus バインディング
+3. **lib.rs**: Magnus初期化と関数登録
+4. **error.rs**: 包括的なエラーハンドリングとRuby例外変換
 
-3. **代替ビルド方法**（rakeが失敗する場合）:
-   ```bash
-   cd ext/rbcsv
-   cargo build --release
-   cp ../../target/release/librbcsv.dylib ../../lib/rbcsv/rbcsv.bundle
-   cd ../..
-   ```
+### 開発時の重要な注意点
 
-### ビルドのトラブルシューティング
+#### Ruby拡張ライブラリの特殊性
 
-#### ABIバージョンの不一致
-「incompatible ABI version」エラーが発生した場合:
+```bash
+# ❌ 避けるべき: cargo buildは直接使用しない
+# cargo build は通常のRustライブラリ用で、Ruby拡張では適切にリンクされない
+
+# ✅ 推奨される開発フロー:
+cd ext/rbcsv
+cargo check           # 構文チェック（リンクなし）
+cargo test            # Rust単体テスト
+cd ../..
+bundle exec rake compile  # Ruby拡張ビルド
+bundle exec rspec     # Ruby統合テスト
+```
 
-1. ビルドと実行で同じRubyバージョンを使用していることを確認
-2. クリーンして再ビルド:
-   ```bash
-   rm -rf lib/rbcsv/rbcsv.bundle tmp/
-   rake compile
-   ```
+#### ビルドコマンドの使い分け
 
-#### Rubyバージョンの競合
-開発版Ruby（3.5.0devなど）を使用する場合、プリコンパイル済みのgemは動作しません。必ずソースから再ビルドしてください。
+| コマンド | 用途 | 場所 | 備考 |
+|---------|------|------|------|
+| `cargo check` | 構文・型チェック | ext/rbcsv | 高速、リンクなし |
+| `cargo test` | Rust単体テスト | ext/rbcsv | Rubyシンボル不要 |
+| `cargo build` | **使用不可** | - | リンクエラーが発生 |
+| `bundle exec rake compile` | Ruby拡張ビルド | プロジェクトルート | 本番用ビルド |
+| `bundle exec rspec` | 統合テスト | プロジェクトルート | 完全な機能テスト |
 
 ## リリース手順
 
-### 1. バージョンの更新
+### 1. 準備フェーズ
+
+```bash
+# 開発状況の確認
+git status
+git log --oneline -10
+
+# 全テストの実行
+rake clean
+rake
+
+# コードスタイルチェック
+bundle exec rubocop
+cd ext/rbcsv && cargo clippy && cd ../..
+```
+
+### 2. バージョン更新
+
+```bash
+# lib/rbcsv/version.rb を編集
+vim lib/rbcsv/version.rb
+```
 
-`lib/rbcsv/version.rb`を編集:
 ```ruby
 module RbCsv
-  VERSION = "x.y.z"  # バージョン番号を更新
+  VERSION = "x.y.z"  # セマンティックバージョニング
 end
 ```
 
-### 2. CHANGELOG.mdの更新
+### 3. CHANGELOG.md の更新
 
-リリース用の新しいセクションを追加:
 ```markdown
 ## [x.y.z] - YYYY-MM-DD
 
-- **修正**: バグ修正の説明
-- **追加**: 新機能の説明
-- **変更**: 変更点の説明
-- **削除**: 削除された機能の説明
+### 追加
+- 新機能の説明
+
+### 変更
+- 既存機能の変更点
+
+### 修正
+- バグ修正の説明
+
+### 削除
+- 削除された機能（非互換性のある変更）
+
+### セキュリティ
+- セキュリティ関連の修正
 ```
 
-### 3. ビルドとテスト
+### 4. ビルドとテスト
 
 ```bash
-# クリーンビルド
-rm -rf lib/rbcsv/rbcsv.bundle tmp/
-
-# 拡張の再ビルド
+# フルクリーンビルド
+rake clean
+bundle install
 rake compile
 
-# 機能テスト
-ruby -I lib -e "require 'rbcsv'; p RbCsv.parse('a,b\n1,2')"
+# 統合テスト
+rake spec
 
-# テストスイートの実行
-bundle exec rspec
+# 動作確認
+ruby -I lib -e "require 'rbcsv'; puts RbCsv::VERSION"
+ruby -I lib -e "require 'rbcsv'; p RbCsv.parse('a,b\n1,2', {})"
 ```
 
-### 4. Gemのビルド
+### 5. Gemビルド
 
 ```bash
+# Gemファイル生成
 gem build rbcsv.gemspec
-```
 
-これにより、現在のディレクトリに`rbcsv-x.y.z.gem`が作成されます。
+# 生成確認
+ls -la rbcsv-*.gem
+```
 
-### 5. 変更のコミット
+### 6. 変更のコミット
 
 ```bash
 git add -A
-git commit -m "Release vx.y.z
+git commit -m "Release v${VERSION}
 
-- 主な変更点の簡潔な説明
-- 重要な改善や修正のリスト"
+主な変更:
+- 変更点1の説明
+- 変更点2の説明
+- バグ修正やパフォーマンス改善"
 ```
 
-### 6. Gitタグの作成
+### 7. タグ作成とプッシュ
 
 ```bash
-git tag vx.y.z
+VERSION=$(ruby -I lib -e "require 'rbcsv/version'; puts RbCsv::VERSION")
+git tag "v${VERSION}"
+git push origin main
+git push origin "v${VERSION}"
 ```
 
-### 7. リポジトリへのプッシュ
+### 8. Gem公開（オプション）
 
 ```bash
-git push origin main
-git push origin vx.y.z
+# RubyGems.orgへの公開
+gem push rbcsv-${VERSION}.gem
+
+# 公開確認
+gem list rbcsv --remote
 ```
 
-### 8. Gemの公開（オプション）
+## 開発のベストプラクティス
+
+### コードスタイル
 
-RubyGems.orgに公開する場合:
+#### Ruby
+- 標準的なRuby Style Guideに従う
+- RuboCop設定を使用（`.rubocop.yml`）
+- frozen_string_literalを有効化
 
+#### Rust
 ```bash
-gem push rbcsv-x.y.z.gem
+# フォーマット
+cargo fmt
+
+# リント
+cargo clippy -- -D warnings
+
+# ドキュメント生成
+cargo doc --open
 ```
 
-**注意**: RubyGems.orgの適切な認証情報が設定されていることを確認してください。
+### テスト戦略
 
-## 開発のヒント
+1. **単体テスト**: 各Rustモジュールに対するcargo test
+2. **統合テスト**: Ruby APIレベルでのRSpecテスト
+3. **パフォーマンステスト**: 大きなCSVファイルでのベンチマーク
+4. **エッジケーステスト**: 不正なCSV、空ファイル、エンコーディング問題
 
-### コードスタイル
+### デバッグ
 
-- 標準的なRubyとRustのフォーマット規約に従う
-- Rustコードのフォーマットには`cargo fmt`を使用
-- 適切なRubyリンティングツールを使用
+#### Rust側のデバッグ
 
-### テスト
+```rust
+// 開発ビルドでのみ有効
+#[cfg(debug_assertions)]
+eprintln!("Debug: {:?}", variable);
+
+// ログ出力（log crateを使用）
+log::debug!("Debug information: {:?}", data);
+```
 
-- 新機能のテストを`spec/`に追加
-- Rustユニットテストを`ext/rbcsv/src/lib.rs`に追加
-- コミット前にすべてのテストが通ることを確認
+#### Ruby側のデバッグ
 
-### デバッグ
+```ruby
+# 詳細エラー情報
+begin
+  RbCsv.parse(invalid_csv, {})
+rescue => e
+  puts "Error: #{e.class} - #{e.message}"
+  puts e.backtrace
+end
+```
 
-Rustコードにデバッグ出力を追加する（開発ビルド用）:
+## よくある問題と解決策
 
-```rust
-#[cfg(not(test))]
-eprintln!("デバッグ情報: {:?}", variable);
+### ビルド関連
+
+**問題**: "incompatible ABI version"
+```bash
+# 解決策: クリーンして同じRubyバージョンで再ビルド
+rm -rf lib/rbcsv/rbcsv.bundle tmp/
+bundle exec rake compile
 ```
 
-これはテスト以外のビルドでのみ出力され、本番環境には影響しません。
+**問題**: Rustコンパイルエラー
+```bash
+# 解決策: Rust依存関係の更新
+cd ext/rbcsv
+cargo update
+cargo clean
+cargo build --release
+cd ../..
+```
+
+### 実行時問題
+
+**問題**: 空配列が返される
+- **原因**: CSVリーダーの`has_headers`設定
+- **解決策**: 最新バージョン（v0.1.4+）を使用
 
-## よくある問題
+**問題**: 日本語CSV文字化け
+- **原因**: エンコーディング問題
+- **解決策**: UTF-8での保存を確認、またはエンコーディング変換
 
-### 拡張が読み込めない
+### パフォーマンス問題
 
-1. 正しいRubyバージョン用に拡張がビルドされているか確認
-2. 拡張ファイルの存在を確認: `lib/rbcsv/rbcsv.bundle`
-3. 再ビルドを試す: `rake compile`
+**問題**: 大きなファイルでメモリ不足
+- **解決策**: ストリーミング処理の実装を検討（将来の機能）
 
-### 空配列が返される
+**問題**: 予想より遅い処理速度
+- **チェック項目**:
+  - ファイルI/O vs メモリ処理
+  - trimオプションの使用
+  - デバッグビルド vs リリースビルド
 
-これはv0.1.4で修正された既知の問題です。CSVリーダーで`has_headers(false)`設定を使用した最新バージョンを使用していることを確認してください。
+## コントリビューションガイドライン
 
-### ビルドの失敗
+### 開発フロー
 
-1. Rustがインストールされ、最新であることを確認
-2. Ruby開発ヘッダーが利用可能であることを確認
-3. ビルドキャッシュをクリア: `rm -rf tmp/`
+1. **Issue作成**: バグ報告や機能要求
+2. **フォーク**: 個人リポジトリへのフォーク
+3. **ブランチ作成**: `feature/new-feature` または `fix/bug-name`
+4. **開発**: コードの実装とテスト追加
+5. **テスト**: 全テストの実行と確認
+6. **プルリクエスト**: 説明と変更内容の詳細
 
-## コントリビューション
+### コミットメッセージ
 
-1. リポジトリをフォーク
-2. 機能ブランチを作成
-3. 変更を実施
-4. 新機能のテストを追加
-5. すべてのテストが通ることを確認
-6. プルリクエストを送信
+```
+[種類] 簡潔な説明（50文字以内）
+
+詳細な説明（必要に応じて）：
+- 変更の理由
+- 実装方法
+- 影響範囲
+
+関連Issue: #123
+```
 
-コードは既存のスタイルに従い、適切なテストを含めてください。
+種類の例:
+- `feat`: 新機能
+- `fix`: バグ修正
+- `docs`: ドキュメント
+- `style`: コードスタイル
+- `refactor`: リファクタリング
+- `test`: テスト追加
+- `chore`: その他（依存関係更新など）
+
+## ロードマップ
+
+### 短期目標（v0.2.x）
+- [ ] カスタム区切り文字サポート
+- [ ] ヘッダー行処理
+- [ ] エラーハンドリングの改善
+
+### 中期目標（v0.3.x）
+- [ ] ストリーミング処理
+- [ ] 非同期処理サポート
+- [ ] Windows完全サポート
+
+### 長期目標（v1.0.x）
+- [ ] 安定したAPI
+- [ ] 包括的なドキュメント
+- [ ] パフォーマンス最適化完了
+
+## 参考リンク
+
+- [Magnus Documentation](https://docs.rs/magnus/)
+- [rb_sys Documentation](https://docs.rs/rb_sys/)
+- [Ruby Extension Guide](https://docs.ruby-lang.org/en/master/extension_rdoc.html)
+- [Cargo Book](https://doc.rust-lang.org/cargo/)
+- [RubyGems Guides](https://guides.rubygems.org/)