├── docs
    └── .gitkeep
├── src
    └── project_name
    │   ├── py.typed
    │   ├── core
    │       ├── __init__.py
    │       └── example.py
    │   ├── utils
    │       ├── __init__.py
    │       ├── helpers.py
    │       └── logging_config.py
    │   ├── __init__.py
    │   └── types.py
├── template
    ├── tests
    │   ├── unit
    │   │   ├── __init__.py
    │   │   ├── test_example.py
    │   │   ├── test_logging.py
    │   │   └── test_helpers.py
    │   ├── integration
    │   │   ├── __init__.py
    │   │   └── test_example.py
    │   ├── property
    │   │   ├── __init__.py
    │   │   └── test_helpers_property.py
    │   └── conftest.py
    └── src
    │   └── template_package
    │       ├── py.typed
    │       ├── core
    │           ├── __init__.py
    │           └── example.py
    │       ├── __init__.py
    │       ├── utils
    │           ├── __init__.py
    │           ├── helpers.py
    │           ├── logging_config.py
    │           └── profiling.py
    │       └── types.py
├── tests
    ├── __init__.py
    ├── unit
    │   └── __init__.py
    ├── integration
    │   └── __init__.py
    ├── property
    │   └── __init__.py
    └── test_dummy.py
├── .gemini
    └── settings.json
├── assets
    └── 和太鼓でドドン.mp3
├── .claude
    ├── commands
    │   ├── gemini-search.md
    │   ├── initialize-project.md
    │   ├── gemini-documentation.md
    │   ├── index.md
    │   ├── ensure-quality.md
    │   ├── analyze.md
    │   ├── write-tests.md
    │   ├── commit-and-pr.md
    │   ├── improve.md
    │   ├── task.md
    │   ├── safe-refactor.md
    │   ├── troubleshoot.md
    │   └── scan.md
    └── settings.json
├── .gitignore
├── .github
    ├── dependabot.yml
    ├── PULL_REQUEST_TEMPLATE.md
    ├── ISSUE_TEMPLATE
    │   ├── bug_report.yml
    │   ├── feature_request.yml
    │   └── claude_code_collaboration.yml
    └── workflows
    │   └── ci.yml
├── LICENSE
├── .pre-commit-config.yaml
├── pyproject.toml
├── scripts
    ├── update_project_name.py
    └── setup.sh
├── Makefile
└── CLAUDE.md


/docs/.gitkeep:
--------------------------------------------------------------------------------
1 | 


--------------------------------------------------------------------------------
/src/project_name/py.typed:
--------------------------------------------------------------------------------
1 | 


--------------------------------------------------------------------------------
/template/tests/unit/__init__.py:
--------------------------------------------------------------------------------
1 | 


--------------------------------------------------------------------------------
/template/src/template_package/py.typed:
--------------------------------------------------------------------------------
1 | 


--------------------------------------------------------------------------------
/template/tests/integration/__init__.py:
--------------------------------------------------------------------------------
1 | 


--------------------------------------------------------------------------------
/tests/__init__.py:
--------------------------------------------------------------------------------
1 | """Test package."""
2 | 


--------------------------------------------------------------------------------
/tests/unit/__init__.py:
--------------------------------------------------------------------------------
1 | """Unit tests."""
2 | 


--------------------------------------------------------------------------------
/tests/integration/__init__.py:
--------------------------------------------------------------------------------
1 | """Integration tests."""
2 | 


--------------------------------------------------------------------------------
/tests/property/__init__.py:
--------------------------------------------------------------------------------
1 | """Property-based tests."""
2 | 


--------------------------------------------------------------------------------
/.gemini/settings.json:
--------------------------------------------------------------------------------
1 | {
2 |     "contextFileName": "CLAUDE.md"
3 | }
4 | 


--------------------------------------------------------------------------------
/template/tests/property/__init__.py:
--------------------------------------------------------------------------------
1 | """Property-based testing module."""
2 | 


--------------------------------------------------------------------------------
/src/project_name/core/__init__.py:
--------------------------------------------------------------------------------
1 | """Core module for project_name package."""
2 | 


--------------------------------------------------------------------------------
/src/project_name/utils/__init__.py:
--------------------------------------------------------------------------------
1 | """Utilities module for project_name package."""
2 | 


--------------------------------------------------------------------------------
/assets/和太鼓でドドン.mp3:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/discus0434/python-template-for-claude-code/HEAD/assets/和太鼓でドドン.mp3


--------------------------------------------------------------------------------
/tests/test_dummy.py:
--------------------------------------------------------------------------------
1 | """Dummy test for template repository CI."""
2 | 
3 | 
4 | def test_dummy():
5 |     """Dummy test to make CI pass in template repository."""
6 |     assert True
7 | 


--------------------------------------------------------------------------------
/template/src/template_package/core/__init__.py:
--------------------------------------------------------------------------------
 1 | """Core functionality of the package."""
 2 | 
 3 | from .example import ExampleClass, ExampleConfig, process_data
 4 | 
 5 | __all__ = [
 6 |     "ExampleClass",
 7 |     "ExampleConfig",
 8 |     "process_data",
 9 | ]
10 | 


--------------------------------------------------------------------------------
/.claude/commands/gemini-search.md:
--------------------------------------------------------------------------------
 1 | ## Gemini Search
 2 | 
 3 | `gemini` is Google Gemini CLI. You can use it for web search.
 4 | 
 5 | Run web search via Task Tool with `gemini --yolo -p 'WebSearch: ...'`.
 6 | 
 7 | ```bash
 8 | gemini --yolo -p "WebSearch: ..."
 9 | ```
10 | 


--------------------------------------------------------------------------------
/template/src/template_package/__init__.py:
--------------------------------------------------------------------------------
 1 | from .core.example import ExampleClass, ExampleConfig, process_data
 2 | from .utils.logging_config import get_logger, set_log_level, setup_logging
 3 | 
 4 | __all__ = [
 5 |     "ExampleClass",
 6 |     "ExampleConfig",
 7 |     "get_logger",
 8 |     "process_data",
 9 |     "set_log_level",
10 |     "setup_logging",
11 | ]
12 | 


--------------------------------------------------------------------------------
/src/project_name/__init__.py:
--------------------------------------------------------------------------------
 1 | from .core.example import ExampleClass, ExampleConfig, process_data
 2 | from .utils.logging_config import get_logger, set_log_level, setup_logging
 3 | 
 4 | __all__ = [
 5 |     "ExampleClass",
 6 |     "ExampleConfig",
 7 |     "get_logger",
 8 |     "process_data",
 9 |     "set_log_level",
10 |     "setup_logging",
11 | ]
12 | 
13 | __version__ = "0.1.0"
14 | 


--------------------------------------------------------------------------------
/.claude/commands/initialize-project.md:
--------------------------------------------------------------------------------
 1 | # プロジェクトの初期化
 2 | 
 3 | テンプレートリポジトリの初期化を行います。以下のTODOに従って作業を進めてください。
 4 | 
 5 | - [ ] プロジェクトの概要がユーザーから提供されていない場合、ユーザーにプロジェクトの概要について質問を行う。ユーザー体験の観点から、一問一答で質問することが推奨されます。
 6 | - [ ] `CLAUDE.md`の「プロジェクト概要」セクションをプロジェクトに特化したものに更新し、既存の記述を削除する。
 7 | - [ ] `CLAUDE.md`の「詳細ガイドの参照」セクションをプロジェクトに特化したものに更新し、既存の記述を削除する。
 8 | - [ ] `pyproject.toml`の`dependencies`セクションを更新する。
 9 | - [ ] `tests/`ディレクトリにあるダミーのテストコードを削除する。
10 | 


--------------------------------------------------------------------------------
/template/src/template_package/utils/__init__.py:
--------------------------------------------------------------------------------
 1 | """Utility functions for the package."""
 2 | 
 3 | from .helpers import chunk_list, flatten_dict, load_json_file, save_json_file
 4 | from .logging_config import get_logger, set_log_level, setup_logging
 5 | 
 6 | __all__ = [
 7 |     "chunk_list",
 8 |     "flatten_dict",
 9 |     "get_logger",
10 |     "load_json_file",
11 |     "save_json_file",
12 |     "set_log_level",
13 |     "setup_logging",
14 | ]
15 | 


--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
 1 | # Python
 2 | __pycache__/
 3 | *.py[cod]
 4 | *$py.class
 5 | *.so
 6 | .Python
 7 | *.egg-info/
 8 | dist/
 9 | build/
10 | .eggs/
11 | *.egg
12 | .python-version
13 | 
14 | # Virtual Environment
15 | .venv/
16 | venv/
17 | ENV/
18 | env/
19 | 
20 | # IDE
21 | .vscode/
22 | .idea/
23 | *.swp
24 | *.swo
25 | *~
26 | .DS_Store
27 | 
28 | # Testing
29 | .coverage
30 | .pytest_cache/
31 | htmlcov/
32 | .mypy_cache/
33 | .ruff_cache/
34 | test-results.xml
35 | coverage.xml
36 | .tox/
37 | .hypothesis/
38 | 
39 | # Local
40 | .env
41 | .env.local
42 | *.log
43 | 
44 | # Documentation
45 | .sphinx/
46 | 
47 | # Project specific
48 | .secrets.baseline
49 | 


--------------------------------------------------------------------------------
/.claude/commands/gemini-documentation.md:
--------------------------------------------------------------------------------
 1 | ## Gemini Documentation
 2 | 
 3 | `gemini` is Google Gemini CLI. Gemini excels in writing, so you should use it for documentation, or proofreading.
 4 | 
 5 | Run `gemini` via Task Tool with `gemini --yolo -p '...(instruction)...'`.
 6 | 
 7 | The more you describe the instruction in detail, the better. If you ask Gemini to write or update a document rather than proofreading, you should provide a comprehensive background information like what is written in `CLAUDE.md` or `README.md`.
 8 | 
 9 | Documentation or proofreading is done automatically by Gemini.
10 | 
11 | ```bash
12 | gemini --yolo -p "...(instruction)..."
13 | ```
14 | 


--------------------------------------------------------------------------------
/.github/dependabot.yml:
--------------------------------------------------------------------------------
 1 | version: 2
 2 | updates:
 3 |   # Python dependencies
 4 |   - package-ecosystem: "pip"
 5 |     directory: "/"
 6 |     schedule:
 7 |       interval: "weekly"
 8 |       day: "monday"
 9 |       time: "00:00"
10 |     open-pull-requests-limit: 10
11 |     labels:
12 |       - "dependencies"
13 |       - "python"
14 |     commit-message:
15 |       prefix: "chore"
16 |       include: "scope"
17 |     pull-request-branch-name:
18 |       separator: "-"
19 | 
20 |   # GitHub Actions
21 |   - package-ecosystem: "github-actions"
22 |     directory: "/"
23 |     schedule:
24 |       interval: "weekly"
25 |       day: "monday"
26 |       time: "00:00"
27 |     open-pull-requests-limit: 5
28 |     labels:
29 |       - "dependencies"
30 |       - "github-actions"
31 |     commit-message:
32 |       prefix: "ci"
33 |       include: "scope"
34 | 


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


--------------------------------------------------------------------------------
/.claude/commands/index.md:
--------------------------------------------------------------------------------
 1 | # SuperClaude コマンドリファレンス
 2 | 
 3 | このディレクトリには、Pythonプロジェクト開発を効率化するためのカスタムスラッシュコマンドが定義されています。
 4 | 
 5 | ## コマンドカテゴリ
 6 | 
 7 | ### 分析・改善
 8 | - `/analyze` - 多次元コード分析（品質、セキュリティ、パフォーマンス）
 9 | - `/improve` - エビデンスベースの改善提案と実装
10 | - `/scan` - セキュリティと品質の包括的検証
11 | 
12 | ### 開発・デバッグ
13 | - `/troubleshoot` - 体系的なデバッグとトラブルシューティング
14 | - `/task` - 複雑なタスクの管理とトラッキング
15 | 
16 | ## 基本的な使用方法
17 | 
18 | ```bash
19 | # コード品質の分析
20 | /analyze --code
21 | 
22 | # パフォーマンスの改善
23 | /improve --perf --iterate
24 | 
25 | # セキュリティスキャン
26 | /scan --security --owasp
27 | 
28 | # タスクの作成と管理
29 | /task:create "新機能の実装"
30 | ```
31 | 
32 | ## 既存ツールとの連携
33 | 
34 | これらのコマンドは、プロジェクトの既存ツールと連携して動作します：
35 | 
36 | - `make format/lint/typecheck` - コード品質チェック
37 | - `make test` - テスト実行
38 | - `make security/audit` - セキュリティ検証
39 | - `uv` - パッケージ管理
40 | - `gh` - GitHub操作
41 | 
42 | ## 効率的なワークフロー
43 | 
44 | ### 新機能開発
45 | ```bash
46 | /task:create "機能名" → /analyze → 実装 → /improve → /scan --validate → make test
47 | ```
48 | 
49 | ### バグ修正
50 | ```bash
51 | /troubleshoot --fix → /analyze --code → 修正 → make test → /scan --validate
52 | ```
53 | 
54 | ### パフォーマンス最適化
55 | ```bash
56 | /analyze --perf → /improve --perf --iterate → make benchmark → /scan --validate
57 | ```
58 | 
59 | ## 記号体系
60 | 
61 | 効率的なコミュニケーションのための記号：
62 | 
63 | - `→` : 処理の流れ
64 | - `|` : 選択・区切り
65 | - `&` : 結合・並列
66 | - `:` : 定義
67 | - `»` : シーケンス
68 | - `@` : 場所・参照
69 | 


--------------------------------------------------------------------------------
/.github/PULL_REQUEST_TEMPLATE.md:
--------------------------------------------------------------------------------
 1 | ## 概要
 2 | <!-- このPRで何を変更したか、なぜ変更したかを簡潔に説明してください -->
 3 | 
 4 | ## 変更内容
 5 | <!-- 主な変更点をリストアップしてください -->
 6 | -
 7 | -
 8 | -
 9 | 
10 | ## 変更の種類
11 | <!-- 該当するものにチェックを入れてください -->
12 | - [ ] 🐛 バグ修正 (Bug fix)
13 | - [ ] ✨ 新機能 (New feature)
14 | - [ ] 💥 破壊的変更 (Breaking change)
15 | - [ ] 📝 ドキュメント (Documentation)
16 | - [ ] ♻️ リファクタリング (Refactoring)
17 | - [ ] 🎨 スタイル修正 (Style)
18 | - [ ] 🚀 パフォーマンス改善 (Performance)
19 | - [ ] ✅ テスト (Test)
20 | - [ ] 🔧 設定変更 (Configuration)
21 | - [ ] ⬆️ 依存関係更新 (Dependencies)
22 | 
23 | ## チェックリスト
24 | <!-- PRを提出する前に、以下の項目を確認してください -->
25 | ### コード品質
26 | - [ ] コードが正しくフォーマットされている (`uv run ruff format .`)
27 | - [ ] リンターのチェックをパスしている (`uv run ruff check .`)
28 | - [ ] 型チェックをパスしている (`uv run mypy src/ --strict`)
29 | - [ ] すべてのテストがパスしている (`uv run pytest`)
30 | - [ ] pre-commitフックが正常に動作する (`uv run pre-commit run --all-files`)
31 | 
32 | ### 開発・ドキュメント
33 | - [ ] 新機能/修正に対するテストを追加した
34 | - [ ] ドキュメントを更新した（必要な場合）
35 | - [ ] CLAUDE.mdに新しいパターンを追加した（必要な場合）
36 | - [ ] CHANGELOG.mdを更新した（該当する場合）
37 | 
38 | ### Claude Code協働
39 | - [ ] Claude Codeとの協働で作成された場合、適切なコミットメッセージを使用
40 | - [ ] 新しいコーディングパターンがCLAUDE.mdに反映されている
41 | - [ ] 複雑な実装に対して適切なコメントを追加した
42 | 
43 | ## テスト
44 | <!-- どのようにテストしたか、どのようなテストケースを追加したかを説明してください -->
45 | 
46 | ## スクリーンショット
47 | <!-- UIの変更がある場合は、前後のスクリーンショットを追加してください -->
48 | 
49 | ## 関連Issue
50 | <!-- 関連するIssueがある場合は、リンクしてください -->
51 | Closes #
52 | 
53 | ## その他
54 | <!-- レビュアーに伝えたいことがあれば記載してください -->
55 | 


--------------------------------------------------------------------------------
/.claude/commands/ensure-quality.md:
--------------------------------------------------------------------------------
 1 | # コード品質の自動改善
 2 | 
 3 | `make check-all`が成功するまで、自動的にコードを修正してコード品質を保証します。
 4 | 
 5 | このコマンドは、CLAUDE.mdの「コード品質を保証する」セクションに従い、以下の順序で品質チェックと修正を実行します：
 6 | 
 7 | 1. **コードフォーマット** (`make format`) - Ruffによる自動フォーマット
 8 | 2. **リントチェック** (`make lint`) - Ruffによるリントチェックと自動修正
 9 | 3. **型チェック** (`make typecheck`) - mypyによる厳格な型チェック
10 | 4. **テスト実行** (`make test`) - 全テストの実行
11 | 
12 | ## 実行手順
13 | 
14 | 1. まず `make check-all` を実行して現在の状態を確認
15 | 2. エラーが発生した場合、以下の優先順位で修正を試みる：
16 |    - フォーマットエラー: `make format` で自動修正
17 |    - リントエラー: `make lint` で自動修正可能なものは修正、手動修正が必要なものは詳細を報告
18 |    - 型エラー: エラーメッセージを分析し、適切な型ヒントや型キャストを追加
19 |    - テスト失敗: 失敗原因を特定し、コードまたはテストを修正
20 | 
21 | 3. 各修正後に `make check-all` を再実行し、すべてのチェックが通るまで繰り返す
22 | 
23 | ## 重要な注意事項
24 | 
25 | - **CLAUDE.mdの規約に従う**: 型ヒント、エラーメッセージ、コーディングスタイルはCLAUDE.mdの規約に準拠
26 | - **既存の動作を保持**: テストが失敗した場合、まず実装が仕様通りかを確認し、必要に応じてテストも修正
27 | - **段階的な修正**: 一度にすべてを修正せず、エラーの種類ごとに段階的に対処
28 | - **進捗の報告**: 各ステップでの修正内容と結果を明確に報告
29 | 
30 | ## エラー対処の具体例
31 | 
32 | ### 型エラーの例
33 | ```python
34 | # エラー: Incompatible return value type (got "None", expected "str")
35 | def get_name() -> str:
36 |     return None  # 修正前
37 | 
38 | # 修正後
39 | def get_name() -> str | None:
40 |     return None
41 | ```
42 | 
43 | ### リントエラーの例
44 | ```python
45 | # エラー: F401 'os' imported but unused
46 | import os  # 修正: 未使用のインポートを削除
47 | 
48 | # エラー: E501 line too long (120 > 100 characters)
49 | # 修正: 長い行を適切に改行
50 | ```
51 | 
52 | このコマンドを実行することで、プロジェクトのコード品質を一貫して高いレベルに保つことができます。
53 | 


--------------------------------------------------------------------------------
/.pre-commit-config.yaml:
--------------------------------------------------------------------------------
 1 | repos:
 2 |   # Standard hooks
 3 |   - repo: https://github.com/pre-commit/pre-commit-hooks
 4 |     rev: v5.0.0
 5 |     hooks:
 6 |       - id: trailing-whitespace
 7 |       - id: end-of-file-fixer
 8 |       - id: check-yaml
 9 |       - id: check-toml
10 |       - id: check-json
11 |       - id: check-added-large-files
12 |       - id: check-merge-conflict
13 |       - id: debug-statements
14 | 
15 |   # Python formatting and linting
16 |   - repo: https://github.com/astral-sh/ruff-pre-commit
17 |     rev: v0.6.0
18 |     hooks:
19 |       - id: ruff
20 |         args: [--fix, --exit-non-zero-on-fix, --config=pyproject.toml]
21 |       - id: ruff-format
22 | 
23 |   # Type checking
24 |   - repo: local
25 |     hooks:
26 |       - id: pyright
27 |         name: pyright
28 |         entry: uv run pyright
29 |         language: system
30 |         files: ^src/
31 |         types: [python]
32 | 
33 |   # Security
34 |   - repo: https://github.com/PyCQA/bandit
35 |     rev: 1.7.9
36 |     hooks:
37 |       - id: bandit
38 |         args: [-c, pyproject.toml]
39 |         additional_dependencies: ["bandit[toml]"]
40 | 
41 |   # Dependency vulnerability scanning
42 |   - repo: https://github.com/pypa/pip-audit
43 |     rev: v2.7.3
44 |     hooks:
45 |       - id: pip-audit
46 |         args: [--desc, --fix]
47 | 
48 |   # Secret detection (optional - uncomment if needed)
49 |   # - repo: https://github.com/Yelp/detect-secrets
50 |   #   rev: v1.5.0
51 |   #   hooks:
52 |   #     - id: detect-secrets
53 |   #       args: [--baseline, .secrets.baseline]
54 | 


--------------------------------------------------------------------------------
/.claude/settings.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "permissions": {
 3 |     "allow": [
 4 |       "Bash(claude --version)",
 5 |       "Bash(claude doctor)",
 6 |       "Bash(grep:*)",
 7 |       "Bash(find:*)",
 8 |       "Bash(ls:*)"
 9 |     ],
10 |     "deny": [
11 |       "Bash(rm -rf:*)",
12 |       "Bash(rm -fr:*)",
13 |       "Bash(rm -fR:*)",
14 |       "Bash(rm -Rf:*)",
15 |       "Bash(sudo rm -rf:*)",
16 |       "Bash(sudo rm -fr:*)",
17 |       "Bash(sudo rm -fR:*)",
18 |       "Bash(sudo rm -Rf:*)",
19 |       "Bash(mv /* /dev/null)",
20 |       "Bash(mv ~ /dev/null)",
21 |       "Bash(python -c 'import os; os.system(\"rm -rf /\")')",
22 |       "Bash(perl -e 'unlink glob \"/*\"')",
23 |       "Bash(find / -delete)",
24 |       "Bash(find ~ -delete)",
25 |       "Bash(find . -delete)",
26 |       "Bash(find / -exec rm -rf {} \\;)",
27 |       "Bash(find ~ -exec rm -rf {} \\;)",
28 |       "Bash(find / -exec rm {} \\;)",
29 |       "Bash(find ~ -exec rm {} \\;)",
30 |       "Bash(shred -vfz /dev/sda)",
31 |       "Bash(shred -vfz /dev/sdb)",
32 |       "Bash(cat /dev/urandom > /dev/mem)",
33 |       "Bash(yes | rm -rf /)",
34 |       "Bash(yes | rm -rf ~)",
35 |       "Bash(kill -9 -1)",
36 |       "Bash(killall -9 *)",
37 |       "Bash(pkill -9 -f .)",
38 |       "Bash(shutdown -h now)",
39 |       "Bash(shutdown -r now)",
40 |       "Bash(poweroff)",
41 |       "Bash(reboot)",
42 |       "Bash(halt)",
43 |       "Bash(systemctl poweroff)",
44 |       "Bash(systemctl reboot)",
45 |       "Bash(systemctl halt)",
46 |       "Bash(crontab -r)",
47 |       "Bash(format c:)",
48 |       "Bash(format /)"
49 |     ]
50 |   },
51 |   "hooks": {
52 |     "Stop": [
53 |       {
54 |         "matcher": "",
55 |         "hooks": [
56 |           {
57 |             "type": "command",
58 |             "command": "play assets/和太鼓でドドン.mp3"
59 |           }
60 |         ]
61 |       }
62 |     ]
63 |   }
64 | }
65 | 


--------------------------------------------------------------------------------
/.claude/commands/analyze.md:
--------------------------------------------------------------------------------
  1 | # /analyze - 多次元コード分析
  2 | 
  3 | **目的**: コード、アーキテクチャ、セキュリティ、パフォーマンスの包括的な分析
  4 | 
  5 | ## 概要
  6 | 
  7 | `/analyze`コマンドは、Pythonプロジェクトの様々な側面を分析し、エビデンスベースの改善提案を提供します。
  8 | 
  9 | ## 使用方法
 10 | 
 11 | ```bash
 12 | /analyze [オプション] [対象]
 13 | ```
 14 | 
 15 | ## オプション
 16 | 
 17 | ### --code
 18 | コード品質の分析を実行：
 19 | - 命名規則の一貫性
 20 | - 関数・クラスの複雑性（サイクロマティック複雑性）
 21 | - DRY原則の遵守状況
 22 | - 型ヒントのカバレッジ
 23 | - docstringの品質
 24 | 
 25 | ### --arch
 26 | アーキテクチャの分析：
 27 | - レイヤー間の結合度
 28 | - 依存関係の方向性
 29 | - 設計パターンの適用状況
 30 | - モジュール間の責務分離
 31 | - スケーラビリティの評価
 32 | 
 33 | ### --security
 34 | セキュリティ監査：
 35 | - OWASP Top 10の脆弱性チェック
 36 | - 認証・認可の実装確認
 37 | - 入力検証とサニタイゼーション
 38 | - 暗号化とデータ保護
 39 | - エラーハンドリングの安全性
 40 | 
 41 | ### --perf
 42 | パフォーマンス分析：
 43 | - アルゴリズムの時間計算量
 44 | - メモリ使用効率
 45 | - I/O操作の最適化機会
 46 | - データベースクエリの効率性
 47 | - キャッシング機会の特定
 48 | 
 49 | ### 分析深度フラグ
 50 | - `--think`: 標準的な分析（デフォルト）
 51 | - `--think-hard`: 深い分析
 52 | - `--ultrathink`: 最も詳細な分析
 53 | 
 54 | ## 実行例
 55 | 
 56 | ### 基本的な使用
 57 | ```bash
 58 | # カレントディレクトリのコード品質分析
 59 | /analyze --code
 60 | 
 61 | # 特定ファイルのセキュリティ監査
 62 | /analyze --security src/auth/
 63 | 
 64 | # 全体的なアーキテクチャ分析
 65 | /analyze --arch --think-hard
 66 | ```
 67 | 
 68 | ### 複合分析
 69 | ```bash
 70 | # コードとセキュリティの包括的分析
 71 | /analyze --code --security --think-hard
 72 | 
 73 | # パフォーマンスボトルネックの特定
 74 | /analyze --perf --ultrathink src/core/
 75 | ```
 76 | 
 77 | ## 出力形式
 78 | 
 79 | 分析結果は以下の形式で提供されます：
 80 | 
 81 | ```yaml
 82 | 分析サマリー:
 83 |   対象: [分析対象のパス]
 84 |   実行時間: [分析にかかった時間]
 85 | 
 86 | 発見事項:
 87 |   重大度: CRITICAL|HIGH|MEDIUM|LOW
 88 |   カテゴリ: [問題のカテゴリ]
 89 |   場所: [ファイル:行番号]
 90 |   説明: [問題の詳細]
 91 |   証拠: [メトリクスや具体例]
 92 |   推奨対応: [改善案]
 93 | 
 94 | メトリクス:
 95 |   コード品質スコア: [0-100]
 96 |   セキュリティスコア: [0-100]
 97 |   パフォーマンススコア: [0-100]
 98 |   テストカバレッジ: [パーセンテージ]
 99 | ```
100 | 
101 | ## 既存ツールとの連携
102 | 
103 | `/analyze`は以下のツールと連携して動作します：
104 | 
105 | - `mypy`: 型チェックの結果を統合
106 | - `ruff`: リンター出力を分析に含める
107 | - `bandit`: セキュリティ問題の検出
108 | - `pytest`: テストカバレッジの確認
109 | 
110 | ## 注意事項
111 | 
112 | - 大規模なコードベースでは`--ultrathink`の使用に時間がかかる場合があります
113 | - セキュリティ分析は補完的なツールとして使用し、専門的なセキュリティ監査の代替にはなりません
114 | - パフォーマンス分析は静的解析に基づくため、実際のベンチマークと併用してください
115 | 


--------------------------------------------------------------------------------
/.claude/commands/write-tests.md:
--------------------------------------------------------------------------------
  1 | # t-wada流TDDによるテスト作成
  2 | 
  3 | CLAUDE.mdの「テスト戦略」セクションで定義されているt-wada流のテスト駆動開発（TDD）に従って、高品質なテストを作成します。
  4 | 
  5 | ## TDDの基本サイクル
  6 | 
  7 | 1. 🔴 **Red**: 失敗するテストを書く
  8 | 2. 🟢 **Green**: テストを通す最小限の実装
  9 | 3. 🔵 **Refactor**: リファクタリング
 10 | 
 11 | ## 実行手順
 12 | 
 13 | ### 1. TODOリストの作成
 14 | 実装したい機能をリストアップし、最小単位に分解します：
 15 | ```
 16 | [ ] 基本的な機能の動作確認
 17 | [ ] エッジケースの処理
 18 | [ ] エラーハンドリング
 19 | [ ] パフォーマンスが重要な場合はベンチマーク
 20 | ```
 21 | 
 22 | ### 2. テストファイルの配置
 23 | ```
 24 | tests/
 25 | ├── unit/            # 単体テスト
 26 | ├── property/        # プロパティベーステスト（Hypothesis使用）
 27 | ├── integration/     # 統合テスト
 28 | └── conftest.py      # pytestフィクスチャ
 29 | ```
 30 | 
 31 | ### 3. テストの命名規則
 32 | 日本語で意図を明確に表現します：
 33 | ```python
 34 | def test_正常系_有効なデータで処理成功():
 35 |     """chunk_listが正しくチャンク化できることを確認。"""
 36 | 
 37 | def test_異常系_不正なサイズでValueError():
 38 |     """チャンクサイズが0以下の場合、ValueErrorが発生することを確認。"""
 39 | 
 40 | def test_エッジケース_空リストで空結果():
 41 |     """空のリストをチャンク化すると空の結果が返されることを確認。"""
 42 | ```
 43 | 
 44 | ### 4. templateディレクトリの参考例
 45 | 
 46 | **単体テスト** (@template/tests/unit/test_example.py)
 47 | - 関数・クラスの基本動作
 48 | - 正常系・異常系・エッジケース
 49 | - パラメトライズテストの活用
 50 | 
 51 | **プロパティベーステスト** (@template/tests/property/test_helpers_property.py)
 52 | - Hypothesisによる自動テストケース生成
 53 | - 不変条件の検証
 54 | - エッジケースの自動発見
 55 | 
 56 | **統合テスト** (@template/tests/integration/test_example.py)
 57 | - コンポーネント間の連携
 58 | - ファイルI/Oやデータ処理パイプライン
 59 | - エラーのカスケード処理
 60 | 
 61 | ## 三角測量の実践例
 62 | 
 63 | ```python
 64 | # Step 1: 最初のテスト（仮実装で通す）
 65 | def test_add_正の数():
 66 |     assert add(2, 3) == 5
 67 | 
 68 | def add(a, b):
 69 |     return 5  # 仮実装
 70 | 
 71 | # Step 2: 2つ目のテスト（一般化を促す）
 72 | def test_add_別の正の数():
 73 |     assert add(1, 4) == 5
 74 |     assert add(10, 20) == 30  # これで仮実装では通らない
 75 | 
 76 | def add(a, b):
 77 |     return a + b  # 一般化
 78 | 
 79 | # Step 3: エッジケースを追加
 80 | def test_add_負の数():
 81 |     assert add(-1, -2) == -3
 82 |     assert add(-5, 3) == -2
 83 | ```
 84 | 
 85 | ## TDD実践時の注意点
 86 | 
 87 | 1. **テストは1つずつ追加** - 一度に複数のテストを書かない
 88 | 2. **小さく頻繁にコミット** - Red→Green、Refactor完了でコミット
 89 | 3. **テストの粒度** - 1つのテストで1つの振る舞いをテスト
 90 | 4. **リファクタリングの判断** - 重複コード、可読性、設計原則
 91 | 5. **テストファーストの徹底** - 必ず失敗するテストから書く
 92 | 
 93 | ## 実行コマンド
 94 | 
 95 | ```bash
 96 | # テストの実行
 97 | make test              # 全テスト実行
 98 | make test-unit         # 単体テストのみ
 99 | make test-property     # プロパティベーステストのみ
100 | make test-cov          # カバレッジ付きテスト
101 | 
102 | # 特定のテストを実行
103 | uv run pytest tests/unit/test_example.py::TestExampleClass::test_正常系_初期化時は空のリスト -v
104 | ```
105 | 
106 | このコマンドを使用することで、堅牢で保守性の高いテストスイートを構築できます。
107 | 


--------------------------------------------------------------------------------
/.github/ISSUE_TEMPLATE/bug_report.yml:
--------------------------------------------------------------------------------
  1 | name: 🐛 バグレポート
  2 | description: バグを報告して改善に協力してください
  3 | title: "[Bug]: "
  4 | labels: ["bug", "triage"]
  5 | 
  6 | body:
  7 |   - type: markdown
  8 |     attributes:
  9 |       value: |
 10 |         バグレポートを提出していただきありがとうございます！
 11 |         できるだけ詳細な情報を提供していただけると、問題の解決が早くなります。
 12 | 
 13 |   - type: textarea
 14 |     id: description
 15 |     attributes:
 16 |       label: バグの説明
 17 |       description: バグの内容を明確かつ簡潔に説明してください
 18 |       placeholder: |
 19 |         何が起こったのか、何を期待していたのかを説明してください
 20 |     validations:
 21 |       required: true
 22 | 
 23 |   - type: textarea
 24 |     id: reproduction
 25 |     attributes:
 26 |       label: 再現手順
 27 |       description: バグを再現するための手順を記載してください
 28 |       placeholder: |
 29 |         1. '...'を実行する
 30 |         2. '...'をクリックする
 31 |         3. '...'が表示される
 32 |         4. エラーが発生する
 33 |     validations:
 34 |       required: true
 35 | 
 36 |   - type: textarea
 37 |     id: expected
 38 |     attributes:
 39 |       label: 期待される動作
 40 |       description: 本来どのような動作を期待していたか説明してください
 41 |     validations:
 42 |       required: true
 43 | 
 44 |   - type: textarea
 45 |     id: actual
 46 |     attributes:
 47 |       label: 実際の動作
 48 |       description: 実際にどのような動作が起こったか説明してください
 49 |     validations:
 50 |       required: true
 51 | 
 52 |   - type: textarea
 53 |     id: logs
 54 |     attributes:
 55 |       label: エラーログ
 56 |       description: 関連するエラーメッセージやスタックトレースがあれば貼り付けてください
 57 |       render: shell
 58 | 
 59 |   - type: dropdown
 60 |     id: python-version
 61 |     attributes:
 62 |       label: Python バージョン
 63 |       description: 使用している Python のバージョンを選択してください
 64 |       options:
 65 |         - Python 3.12
 66 |         - Python 3.13
 67 |         - その他
 68 |     validations:
 69 |       required: true
 70 | 
 71 |   - type: input
 72 |     id: os
 73 |     attributes:
 74 |       label: OS
 75 |       description: 使用している OS を記載してください
 76 |       placeholder: 例, Ubuntu 22.04, macOS 14.0, Windows 11
 77 |     validations:
 78 |       required: true
 79 | 
 80 |   - type: textarea
 81 |     id: additional
 82 |     attributes:
 83 |       label: 追加情報
 84 |       description: その他、問題の解決に役立つ情報があれば記載してください
 85 |       placeholder: |
 86 |         - 依存関係のバージョン
 87 |         - 環境変数
 88 |         - 設定ファイル
 89 |         など
 90 | 
 91 |   - type: checkboxes
 92 |     id: terms
 93 |     attributes:
 94 |       label: チェックリスト
 95 |       description: 以下の項目を確認してください
 96 |       options:
 97 |         - label: 同様の Issue が既に存在しないことを確認しました
 98 |           required: true
 99 |         - label: 最新バージョンで問題が発生することを確認しました
100 |           required: true
101 |         - label: 再現可能な最小限のコード例を提供できます
102 |           required: false
103 | 


--------------------------------------------------------------------------------
/.github/ISSUE_TEMPLATE/feature_request.yml:
--------------------------------------------------------------------------------
  1 | name: ✨ 機能要望
  2 | description: 新しい機能やアイデアを提案してください
  3 | title: "[Feature]: "
  4 | labels: ["enhancement", "triage"]
  5 | 
  6 | body:
  7 |   - type: markdown
  8 |     attributes:
  9 |       value: |
 10 |         新しい機能の提案をありがとうございます！
 11 |         あなたのアイデアがプロジェクトをより良くする助けになります。
 12 | 
 13 |   - type: textarea
 14 |     id: problem
 15 |     attributes:
 16 |       label: 解決したい問題
 17 |       description: この機能要望に関連する問題や課題を説明してください
 18 |       placeholder: |
 19 |         現在、〜という作業をする際に〜という問題があります。
 20 |         これは〜なので不便です。
 21 |     validations:
 22 |       required: true
 23 | 
 24 |   - type: textarea
 25 |     id: solution
 26 |     attributes:
 27 |       label: 提案する解決策
 28 |       description: どのような機能や改善を提案しますか？
 29 |       placeholder: |
 30 |         〜という機能があれば、〜ができるようになります。
 31 |         具体的には〜のような実装を想定しています。
 32 |     validations:
 33 |       required: true
 34 | 
 35 |   - type: textarea
 36 |     id: alternatives
 37 |     attributes:
 38 |       label: 検討した代替案
 39 |       description: 他に検討した解決方法があれば記載してください
 40 |       placeholder: |
 41 |         他の方法として〜も考えましたが、〜という理由で提案する方法が良いと考えました。
 42 | 
 43 |   - type: textarea
 44 |     id: api-example
 45 |     attributes:
 46 |       label: API の使用例
 47 |       description: 提案する機能の使用例を示してください（該当する場合）
 48 |       render: python
 49 |       placeholder: |
 50 |         from project_name import NewFeature
 51 | 
 52 |         feature = NewFeature()
 53 |         result = feature.do_something()
 54 | 
 55 |   - type: dropdown
 56 |     id: priority
 57 |     attributes:
 58 |       label: 優先度
 59 |       description: この機能の重要度をどう考えますか？
 60 |       options:
 61 |         - 低（あれば便利）
 62 |         - 中（効率が大幅に向上する）
 63 |         - 高（これがないと困る）
 64 |     validations:
 65 |       required: true
 66 | 
 67 |   - type: textarea
 68 |     id: additional
 69 |     attributes:
 70 |       label: 追加のコンテキスト
 71 |       description: その他、この機能要望に関する情報があれば追加してください
 72 |       placeholder: |
 73 |         - 参考リンク
 74 |         - 類似機能を持つ他のプロジェクト
 75 |         - スクリーンショット
 76 |         など
 77 | 
 78 |   - type: checkboxes
 79 |     id: contribution
 80 |     attributes:
 81 |       label: 貢献について
 82 |       options:
 83 |         - label: この機能の実装に協力する意思があります
 84 |           required: false
 85 |         - label: この機能のテストに協力する意思があります
 86 |           required: false
 87 |         - label: この機能のドキュメント作成に協力する意思があります
 88 |           required: false
 89 | 
 90 |   - type: checkboxes
 91 |     id: terms
 92 |     attributes:
 93 |       label: チェックリスト
 94 |       description: 以下の項目を確認してください
 95 |       options:
 96 |         - label: 同様の機能要望が既に存在しないことを確認しました
 97 |           required: true
 98 |         - label: この機能がプロジェクトの目的に合致することを確認しました
 99 |           required: true
100 | 


--------------------------------------------------------------------------------
/.claude/commands/commit-and-pr.md:
--------------------------------------------------------------------------------
  1 | # 変更のコミットとPR作成
  2 | 
  3 | 現在の変更をコミットし、適切なブランチを作成してプルリクエストを作成します。CLAUDE.mdの「GitHub操作」セクションの規約に従います。
  4 | 
  5 | ## 実行手順
  6 | 
  7 | ### 1. 変更内容の確認
  8 | ```bash
  9 | git status              # 変更ファイルの確認
 10 | git diff                # 変更内容の確認
 11 | git log --oneline -10   # 最近のコミット履歴を確認
 12 | ```
 13 | 
 14 | ### 2. コミットメッセージの作成
 15 | CLAUDE.mdで定義されているフォーマットに従います：
 16 | ```
 17 | <変更の種類>: <変更内容の要約>
 18 | 
 19 | 詳細な説明（必要に応じて）
 20 | 
 21 | 🤖 Generated with [Claude Code](https://claude.ai/code)
 22 | 
 23 | Co-Authored-By: Claude <noreply@anthropic.com>
 24 | ```
 25 | 
 26 | ### 3. ブランチ名の命名規則
 27 | 変更の種類に応じて適切なプレフィックスを使用：
 28 | - `feature/` - 機能追加
 29 | - `fix/` - バグ修正
 30 | - `refactor/` - リファクタリング
 31 | - `docs/` - ドキュメント更新
 32 | - `test/` - テスト追加・修正
 33 | 
 34 | ### 4. ラベルの命名規則
 35 | PRに付けるラベル：
 36 | - `enhancement` - 機能追加
 37 | - `bug` - バグ修正
 38 | - `refactor` - リファクタリング
 39 | - `documentation` - ドキュメント
 40 | - `test` - テスト
 41 | 
 42 | ### 5. 実行ステップ
 43 | 
 44 | 1. **変更内容の分析**
 45 |    - git statusとgit diffで変更を確認
 46 |    - 変更の種類を判断（feature/fix/refactor/docs/test）
 47 | 
 48 | 2. **ブランチの作成**
 49 |    ```bash
 50 |    git checkout -b <branch-type>/<descriptive-name>
 51 |    ```
 52 | 
 53 | 3. **ステージングとコミット**
 54 |    ```bash
 55 |    git add <files>
 56 |    git commit -m "$(cat <<'EOF'
 57 |    <type>: <summary>
 58 | 
 59 |    <detailed description if needed>
 60 | 
 61 |    🤖 Generated with [Claude Code](https://claude.ai/code)
 62 | 
 63 |    Co-Authored-By: Claude <noreply@anthropic.com>
 64 |    EOF
 65 |    )"
 66 |    ```
 67 | 
 68 | 4. **リモートへのプッシュ**
 69 |    ```bash
 70 |    git push -u origin <branch-name>
 71 |    ```
 72 | 
 73 | 5. **PRの作成**
 74 |    ```bash
 75 |    make pr TITLE="<PR title>" BODY="<PR description>" LABEL="<label>"
 76 |    # または
 77 |    gh pr create --title "<title>" --body "$(cat <<'EOF'
 78 |    ## Summary
 79 |    - <変更点1>
 80 |    - <変更点2>
 81 | 
 82 |    ## Test plan
 83 |    - [ ] make check-allが成功することを確認
 84 |    - [ ] 関連するテストが追加されていることを確認
 85 |    - [ ] ドキュメントが更新されていることを確認
 86 | 
 87 |    🤖 Generated with [Claude Code](https://claude.ai/code)
 88 |    EOF
 89 |    )"
 90 |    ```
 91 | 
 92 | ## 注意事項
 93 | 
 94 | 1. **コミット前の確認**
 95 |    - `make check-all`が成功することを確認
 96 |    - 不要なファイルが含まれていないことを確認
 97 |    - センシティブな情報が含まれていないことを確認
 98 | 
 99 | 2. **コミットメッセージ**
100 |    - 変更内容を明確に記述
101 |    - なぜ変更したかを説明（whatよりwhy）
102 |    - 日本語での記述も可
103 | 
104 | 3. **PR作成時**
105 |    - テストプランを必ず含める
106 |    - レビュアーが理解しやすい説明を心がける
107 |    - 関連するIssueがあればリンクする
108 | 
109 | ## 使用例
110 | 
111 | ```bash
112 | # 機能追加のPR
113 | make pr TITLE="feat: ユーザー認証機能を追加" BODY="JWTトークンベースの認証システムを実装しました" LABEL="enhancement"
114 | 
115 | # バグ修正のPR
116 | make pr TITLE="fix: ログイン時の500エラーを修正" BODY="認証トークンの検証ロジックを修正しました" LABEL="bug"
117 | 
118 | # ドキュメント更新のPR
119 | make pr TITLE="docs: APIドキュメントを更新" BODY="新しいエンドポイントの説明を追加しました" LABEL="documentation"
120 | ```
121 | 
122 | このコマンドにより、規約に従った一貫性のあるコミットとPR作成が可能になります。
123 | 


--------------------------------------------------------------------------------
/src/project_name/types.py:
--------------------------------------------------------------------------------
  1 | """Common type definitions for the project."""
  2 | 
  3 | from collections.abc import Mapping
  4 | from typing import Literal, TypedDict
  5 | 
  6 | # Status types
  7 | type ProcessorStatus = Literal["success", "error", "pending"]
  8 | type ValidationStatus = Literal["valid", "invalid", "skipped"]
  9 | 
 10 | 
 11 | # Common data structures
 12 | class ItemDict(TypedDict):
 13 |     """Typed dictionary for item data."""
 14 | 
 15 |     id: int
 16 |     name: str
 17 |     value: int
 18 | 
 19 | 
 20 | class ItemDictWithStatus(ItemDict):
 21 |     """Extended item dictionary with status."""
 22 | 
 23 |     status: ProcessorStatus
 24 |     processed: bool
 25 | 
 26 | 
 27 | class ConfigDict(TypedDict, total=False):
 28 |     """Typed dictionary for configuration data."""
 29 | 
 30 |     name: str
 31 |     max_items: int
 32 |     enable_validation: bool
 33 |     debug: bool
 34 |     timeout: float
 35 | 
 36 | 
 37 | class ErrorInfo(TypedDict):
 38 |     """Typed dictionary for error information."""
 39 | 
 40 |     code: str
 41 |     message: str
 42 |     details: Mapping[str, str | int | None]
 43 | 
 44 | 
 45 | # Result types
 46 | class ProcessingResult(TypedDict):
 47 |     """Result of a processing operation."""
 48 | 
 49 |     status: ProcessorStatus
 50 |     data: list[ItemDict]
 51 |     errors: list[ErrorInfo]
 52 |     processed_count: int
 53 |     skipped_count: int
 54 | 
 55 | 
 56 | class ValidationResult(TypedDict):
 57 |     """Result of a validation operation."""
 58 | 
 59 |     is_valid: bool
 60 |     errors: list[str]
 61 |     warnings: list[str]
 62 | 
 63 | 
 64 | # JSON types
 65 | type JSONPrimitive = str | int | float | bool | None
 66 | type JSONValue = JSONPrimitive | Mapping[str, "JSONValue"] | list["JSONValue"]
 67 | type JSONObject = Mapping[str, JSONValue]
 68 | 
 69 | # File operation types
 70 | type FileOperation = Literal["read", "write", "append", "delete"]
 71 | type FileFormat = Literal["json", "yaml", "csv", "txt"]
 72 | 
 73 | # Sorting and filtering
 74 | type SortOrder = Literal["asc", "desc"]
 75 | type FilterOperator = Literal["eq", "ne", "gt", "lt", "gte", "lte", "in", "contains"]
 76 | 
 77 | 
 78 | # Structured logging types
 79 | class LogContext(TypedDict, total=False):
 80 |     """Context information for structured logging."""
 81 | 
 82 |     user_id: str | int | None
 83 |     request_id: str | None
 84 |     session_id: str | None
 85 |     trace_id: str | None
 86 |     module: str | None
 87 |     function: str | None
 88 |     line_number: int | None
 89 |     extra: Mapping[str, JSONValue]
 90 | 
 91 | 
 92 | class LogEvent(TypedDict):
 93 |     """Structured log event."""
 94 | 
 95 |     event: str
 96 |     level: Literal["debug", "info", "warning", "error", "critical"]
 97 |     timestamp: str
 98 |     logger: str
 99 |     context: LogContext | None
100 |     exception: str | None
101 |     duration_ms: float | None
102 | 
103 | 
104 | # Log formatting types
105 | type LogFormat = Literal["json", "console", "plain"]
106 | type LogLevel = Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
107 | 


--------------------------------------------------------------------------------
/.claude/commands/improve.md:
--------------------------------------------------------------------------------
  1 | # /improve - エビデンスベースの改善
  2 | 
  3 | **目的**: 測定可能な証拠に基づいたコード改善の提案と実装
  4 | 
  5 | ## 概要
  6 | 
  7 | `/improve`コマンドは、コード品質、パフォーマンス、アーキテクチャの改善を、具体的な証拠とメトリクスに基づいて実行します。
  8 | 
  9 | ## 使用方法
 10 | 
 11 | ```bash
 12 | /improve [オプション] [対象]
 13 | ```
 14 | 
 15 | ## オプション
 16 | 
 17 | ### --quality
 18 | コード品質の改善：
 19 | - 可読性の向上（命名、構造）
 20 | - 保守性の改善（モジュール化、依存関係）
 21 | - DRY原則の適用
 22 | - 複雑性の削減
 23 | - エラーハンドリングの改善
 24 | 
 25 | ### --perf
 26 | パフォーマンスの最適化：
 27 | - アルゴリズムの効率化
 28 | - メモリ使用量の削減
 29 | - I/O操作の最適化
 30 | - キャッシング戦略の実装
 31 | - 並列処理の活用
 32 | 
 33 | ### --arch
 34 | アーキテクチャの改善：
 35 | - 設計パターンの適用
 36 | - 依存性注入の実装
 37 | - レイヤー分離の強化
 38 | - モジュール境界の明確化
 39 | - スケーラビリティの向上
 40 | 
 41 | ### 実行モードフラグ
 42 | - `--refactor`: 動作を変えずに内部構造を改善
 43 | - `--iterate`: 指定された閾値まで繰り返し改善
 44 | - `--safe`: 保守的な改善のみ実行
 45 | - `--metrics`: 改善前後のメトリクスを表示
 46 | 
 47 | ### 品質閾値
 48 | - `--threshold low`: 基本的な改善
 49 | - `--threshold medium`: 標準的な改善（デフォルト）
 50 | - `--threshold high`: 高品質を目指す改善
 51 | - `--threshold perfect`: 可能な限り最高品質
 52 | 
 53 | ## 実行例
 54 | 
 55 | ### 基本的な使用
 56 | ```bash
 57 | # コード品質の改善
 58 | /improve --quality src/
 59 | 
 60 | # パフォーマンスの反復改善
 61 | /improve --perf --iterate --threshold high
 62 | 
 63 | # 安全なリファクタリング
 64 | /improve --arch --refactor --safe
 65 | ```
 66 | 
 67 | ### 高度な使用
 68 | ```bash
 69 | # メトリクス付き品質改善
 70 | /improve --quality --metrics --threshold perfect
 71 | 
 72 | # 複合的な改善
 73 | /improve --quality --perf --arch --iterate
 74 | ```
 75 | 
 76 | ## 改善プロセス
 77 | 
 78 | 1. **現状分析**
 79 |    - 現在のメトリクスを測定
 80 |    - 改善機会を特定
 81 |    - 優先順位を設定
 82 | 
 83 | 2. **計画立案**
 84 |    - 安全な改善パスを設計
 85 |    - 既存機能の保持を確認
 86 |    - 段階的な変更計画
 87 | 
 88 | 3. **実装**
 89 |    - 小さな原子的変更
 90 |    - 継続的なテスト実行
 91 |    - パフォーマンス監視
 92 | 
 93 | 4. **検証**
 94 |    - 動作の保持を確認
 95 |    - メトリクスの改善を測定
 96 |    - 回帰テストの実行
 97 | 
 98 | ## 出力形式
 99 | 
100 | ```yaml
101 | 改善サマリー:
102 |   対象: [改善対象のパス]
103 |   改善項目数: [実施した改善の数]
104 | 
105 | 改善前メトリクス:
106 |   コード品質スコア: [0-100]
107 |   サイクロマティック複雑性: [平均値]
108 |   パフォーマンススコア: [0-100]
109 | 
110 | 実施した改善:
111 |   - タイプ: [改善の種類]
112 |     場所: [ファイル:行番号]
113 |     変更内容: [具体的な変更]
114 |     根拠: [測定データに基づく理由]
115 |     効果: [期待される改善効果]
116 | 
117 | 改善後メトリクス:
118 |   コード品質スコア: [0-100] (改善率: +X%)
119 |   サイクロマティック複雑性: [平均値] (改善率: -Y%)
120 |   パフォーマンススコア: [0-100] (改善率: +Z%)
121 | ```
122 | 
123 | ## 既存ツールとの連携
124 | 
125 | 改善プロセスは以下のツールを活用：
126 | 
127 | - `make format`: コードフォーマットの統一
128 | - `make lint`: リント違反の自動修正
129 | - `make typecheck`: 型の一貫性確認
130 | - `make test`: 改善後の動作確認
131 | - `make benchmark`: パフォーマンス改善の測定
132 | 
133 | ## 改善パターン
134 | 
135 | ### コード品質
136 | - 長い関数の分割
137 | - ネストの深さ削減
138 | - 明確な変数名への変更
139 | - 型ヒントの追加
140 | - エラーメッセージの改善
141 | 
142 | ### パフォーマンス
143 | - リスト内包表記の活用
144 | - 不要なループの削除
145 | - キャッシュの実装
146 | - 遅延評価の導入
147 | - バッチ処理の実装
148 | 
149 | ### アーキテクチャ
150 | - ファサードパターンの適用
151 | - 依存性の逆転
152 | - インターフェースの抽出
153 | - モジュールの再編成
154 | - 横断的関心事の分離
155 | 
156 | ## 注意事項
157 | 
158 | - `--iterate`モードは処理時間が長くなる可能性があります
159 | - 大規模な変更前は必ずバックアップまたはgitのコミットを作成してください
160 | - パフォーマンス改善は必ずベンチマークで検証してください
161 | - テストカバレッジが低い場合は、先にテストを追加することを推奨します
162 | 


--------------------------------------------------------------------------------
/.github/ISSUE_TEMPLATE/claude_code_collaboration.yml:
--------------------------------------------------------------------------------
  1 | name: 🤖 Claude Code協働の改善
  2 | description: Claude Codeとの協働体験の改善提案
  3 | title: "[Claude Code]: "
  4 | labels: ["claude-code", "enhancement", "triage"]
  5 | 
  6 | body:
  7 |   - type: markdown
  8 |     attributes:
  9 |       value: |
 10 |         Claude Codeとの協働体験の改善にご協力いただきありがとうございます！
 11 |         CLAUDE.mdや開発プロセスの改善提案をお聞かせください。
 12 | 
 13 |   - type: dropdown
 14 |     id: category
 15 |     attributes:
 16 |       label: 改善カテゴリ
 17 |       description: どの分野の改善提案ですか？
 18 |       options:
 19 |         - CLAUDE.mdの内容改善
 20 |         - 開発プロセスの改善
 21 |         - ドキュメント構造の改善
 22 |         - 自動化の追加
 23 |         - その他
 24 |     validations:
 25 |       required: true
 26 | 
 27 |   - type: textarea
 28 |     id: current-problem
 29 |     attributes:
 30 |       label: 現在の問題
 31 |       description: Claude Codeとの協働で困っていることや改善したいことを説明してください
 32 |       placeholder: |
 33 |         - 特定の作業でClaude Codeが迷うことが多い
 34 |         - CLAUDE.mdに足りない情報がある
 35 |         - 繰り返し同じ説明をする必要がある
 36 |         など
 37 |     validations:
 38 |       required: true
 39 | 
 40 |   - type: textarea
 41 |     id: proposed-solution
 42 |     attributes:
 43 |       label: 提案する改善策
 44 |       description: どのような改善を提案しますか？
 45 |       placeholder: |
 46 |         - CLAUDE.mdに〜の情報を追加する
 47 |         - 〜の作業をスクリプト化する
 48 |         - 〜のドキュメントを作成する
 49 |         など
 50 |     validations:
 51 |       required: true
 52 | 
 53 |   - type: textarea
 54 |     id: claude-md-addition
 55 |     attributes:
 56 |       label: CLAUDE.mdへの追加内容（該当する場合）
 57 |       description: CLAUDE.mdに追加したい内容があれば記載してください
 58 |       render: markdown
 59 |       placeholder: |
 60 |         ```markdown
 61 |         ## 新しいセクション
 62 | 
 63 |         ### 説明
 64 |         このセクションでは〜について説明します。
 65 | 
 66 |         ### 例
 67 |         ```python
 68 |         # 例のコード
 69 |         ```
 70 | 
 71 |   - type: textarea
 72 |     id: impact
 73 |     attributes:
 74 |       label: 期待される効果
 75 |       description: この改善により、どのような効果を期待しますか？
 76 |       placeholder: |
 77 |         - Claude Codeとのやり取りが〜％効率化される
 78 |         - 新メンバーのオンボーディング時間が短縮される
 79 |         - 繰り返し作業が自動化される
 80 |         など
 81 | 
 82 |   - type: textarea
 83 |     id: examples
 84 |     attributes:
 85 |       label: 具体例・参考資料
 86 |       description: 具体的な例や参考になる資料があれば記載してください
 87 |       placeholder: |
 88 |         - 他のプロジェクトでの類似例
 89 |         - 参考文献のリンク
 90 |         - スクリーンショット
 91 |         など
 92 | 
 93 |   - type: checkboxes
 94 |     id: contribution
 95 |     attributes:
 96 |       label: 貢献について
 97 |       options:
 98 |         - label: この改善の実装に協力する意思があります
 99 |           required: false
100 |         - label: ドキュメントの作成に協力する意思があります
101 |           required: false
102 |         - label: テスト・検証に協力する意思があります
103 |           required: false
104 | 
105 |   - type: checkboxes
106 |     id: terms
107 |     attributes:
108 |       label: チェックリスト
109 |       description: 以下の項目を確認してください
110 |       options:
111 |         - label: 同様の提案が既に存在しないことを確認しました
112 |           required: true
113 |         - label: この提案がプロジェクトの目的に合致することを確認しました
114 |           required: true
115 | 


--------------------------------------------------------------------------------
/template/src/template_package/types.py:
--------------------------------------------------------------------------------
  1 | """Common type definitions for the project."""
  2 | 
  3 | from collections.abc import Mapping
  4 | from typing import Literal, TypedDict
  5 | 
  6 | # Status types
  7 | type ProcessorStatus = Literal["success", "error", "pending"]
  8 | type ValidationStatus = Literal["valid", "invalid", "skipped"]
  9 | 
 10 | 
 11 | # Common data structures
 12 | class ItemDict(TypedDict):
 13 |     """Typed dictionary for item data."""
 14 | 
 15 |     id: int
 16 |     name: str
 17 |     value: int
 18 | 
 19 | 
 20 | class ItemDictWithStatus(ItemDict):
 21 |     """Extended item dictionary with status."""
 22 | 
 23 |     status: ProcessorStatus
 24 |     processed: bool
 25 | 
 26 | 
 27 | class ConfigDict(TypedDict, total=False):
 28 |     """Typed dictionary for configuration data."""
 29 | 
 30 |     name: str
 31 |     max_items: int
 32 |     enable_validation: bool
 33 |     debug: bool
 34 |     timeout: float
 35 | 
 36 | 
 37 | class ErrorInfo(TypedDict):
 38 |     """Typed dictionary for error information."""
 39 | 
 40 |     code: str
 41 |     message: str
 42 |     details: Mapping[str, str | int | None]
 43 | 
 44 | 
 45 | # Result types
 46 | class ProcessingResult(TypedDict):
 47 |     """Result of a processing operation."""
 48 | 
 49 |     status: ProcessorStatus
 50 |     data: list[ItemDict]
 51 |     errors: list[ErrorInfo]
 52 |     processed_count: int
 53 |     skipped_count: int
 54 | 
 55 | 
 56 | class ValidationResult(TypedDict):
 57 |     """Result of a validation operation."""
 58 | 
 59 |     is_valid: bool
 60 |     errors: list[str]
 61 |     warnings: list[str]
 62 | 
 63 | 
 64 | # JSON types
 65 | type JSONPrimitive = str | int | float | bool | None
 66 | type JSONValue = JSONPrimitive | Mapping[str, "JSONValue"] | list["JSONValue"]
 67 | type JSONObject = Mapping[str, JSONValue]
 68 | 
 69 | # File operation types
 70 | type FileOperation = Literal["read", "write", "append", "delete"]
 71 | type FileFormat = Literal["json", "yaml", "csv", "txt"]
 72 | 
 73 | # Sorting and filtering
 74 | type SortOrder = Literal["asc", "desc"]
 75 | type FilterOperator = Literal["eq", "ne", "gt", "lt", "gte", "lte", "in", "contains"]
 76 | 
 77 | 
 78 | # Structured logging types
 79 | class LogContext(TypedDict, total=False):
 80 |     """Context information for structured logging."""
 81 | 
 82 |     user_id: str | int | None
 83 |     request_id: str | None
 84 |     session_id: str | None
 85 |     trace_id: str | None
 86 |     module: str | None
 87 |     function: str | None
 88 |     line_number: int | None
 89 |     extra: Mapping[str, JSONValue]
 90 | 
 91 | 
 92 | class LogEvent(TypedDict):
 93 |     """Structured log event."""
 94 | 
 95 |     event: str
 96 |     level: Literal["debug", "info", "warning", "error", "critical"]
 97 |     timestamp: str
 98 |     logger: str
 99 |     context: LogContext | None
100 |     exception: str | None
101 |     duration_ms: float | None
102 | 
103 | 
104 | # Log formatting types
105 | type LogFormat = Literal["json", "console", "plain"]
106 | type LogLevel = Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
107 | 


--------------------------------------------------------------------------------
/template/tests/conftest.py:
--------------------------------------------------------------------------------
  1 | """Pytest configuration and fixtures."""
  2 | 
  3 | import logging
  4 | import os
  5 | import tempfile
  6 | from collections.abc import Iterator
  7 | from pathlib import Path
  8 | from typing import Any
  9 | 
 10 | import pytest
 11 | from template_package.core.example import ExampleClass, ExampleConfig
 12 | from template_package.utils.logging_config import set_log_level
 13 | 
 14 | 
 15 | @pytest.fixture
 16 | def example_config() -> ExampleConfig:
 17 |     """Create a test configuration."""
 18 |     return ExampleConfig(
 19 |         name="test",
 20 |         max_items=10,
 21 |         enable_validation=True,
 22 |     )
 23 | 
 24 | 
 25 | @pytest.fixture
 26 | def example_instance(example_config: ExampleConfig) -> ExampleClass:
 27 |     """Create a test ExampleClass instance."""
 28 |     return ExampleClass(example_config)
 29 | 
 30 | 
 31 | @pytest.fixture
 32 | def sample_data() -> list[dict[str, Any]]:
 33 |     """Create sample data for testing."""
 34 |     return [
 35 |         {"id": 1, "name": "Item 1", "value": 100},
 36 |         {"id": 2, "name": "Item 2", "value": 200},
 37 |         {"id": 3, "name": "Item 3", "value": 300},
 38 |     ]
 39 | 
 40 | 
 41 | @pytest.fixture
 42 | def temp_dir() -> Iterator[Path]:
 43 |     """Create a temporary directory for testing."""
 44 |     with tempfile.TemporaryDirectory() as tmpdir:
 45 |         yield Path(tmpdir)
 46 | 
 47 | 
 48 | @pytest.fixture(autouse=True)
 49 | def reset_environment(monkeypatch: pytest.MonkeyPatch) -> None:
 50 |     """Reset environment variables for each test."""
 51 |     # Remove any test-specific environment variables
 52 |     test_env_vars = [var for var in os.environ if var.startswith("TEST_")]
 53 |     for var in test_env_vars:
 54 |         monkeypatch.delenv(var, raising=False)
 55 | 
 56 | 
 57 | @pytest.fixture(scope="session")
 58 | def setup_test_logging() -> None:
 59 |     """Setup basic logging for test session."""
 60 |     # テスト中は標準ライブラリのロギングを使用
 61 |     import logging
 62 | 
 63 |     log_level = os.environ.get("TEST_LOG_LEVEL", "INFO")
 64 |     logging.basicConfig(
 65 |         level=getattr(logging, log_level),
 66 |         format="[%(levelname)s] %(name)s: %(message)s",
 67 |         force=True,
 68 |     )
 69 | 
 70 | 
 71 | @pytest.fixture
 72 | def capture_logs(caplog: pytest.LogCaptureFixture) -> pytest.LogCaptureFixture:
 73 |     """Capture logs for testing with proper level."""
 74 |     # テスト用にログレベルを設定
 75 |     caplog.set_level(logging.DEBUG)
 76 |     return caplog
 77 | 
 78 | 
 79 | @pytest.fixture
 80 | def set_test_log_level():
 81 |     """Fixture to dynamically set log level in tests."""
 82 | 
 83 |     def _set_level(level: str | int) -> None:
 84 |         set_log_level(level)
 85 | 
 86 |     return _set_level
 87 | 
 88 | 
 89 | # pytestの起動時にロギングを設定
 90 | def pytest_configure(config: pytest.Config) -> None:
 91 |     """Configure pytest with structured logging setup."""
 92 |     # テスト実行時の最小限のログ設定
 93 |     log_level = os.environ.get("TEST_LOG_LEVEL", "INFO")  # DEBUGだと詳細すぎる
 94 | 
 95 |     # 標準ライブラリのロギングのみを使用（structlogの問題を回避）
 96 |     import logging
 97 | 
 98 |     logging.basicConfig(
 99 |         level=getattr(logging, log_level),
100 |         format="[%(levelname)s] %(name)s: %(message)s",
101 |         force=True,
102 |     )
103 | 


--------------------------------------------------------------------------------
/.claude/commands/task.md:
--------------------------------------------------------------------------------
  1 | # /task - 複雑なタスクの管理
  2 | 
  3 | **目的**: 大規模な機能開発やリファクタリングのタスク管理とトラッキング
  4 | 
  5 | ## 概要
  6 | 
  7 | `/task`コマンドは、複雑な開発タスクを自動的にサブタスクに分解し、進捗を追跡し、セッション間でのコンテキストを保持します。
  8 | 
  9 | ## 使用方法
 10 | 
 11 | ```bash
 12 | /task:<操作> [引数]
 13 | ```
 14 | 
 15 | ## 操作
 16 | 
 17 | ### :create
 18 | 新しいタスクを作成し、自動的にサブタスクに分解：
 19 | ```bash
 20 | /task:create "OAuth 2.0認証システムの実装"
 21 | ```
 22 | 
 23 | 作成時の自動処理：
 24 | - タスクの複雑性分析
 25 | - サブタスクへの自動分解
 26 | - 依存関係の特定
 27 | - 工数の見積もり
 28 | - マイルストーンの設定
 29 | 
 30 | ### :status
 31 | タスクの現在の状態を確認：
 32 | ```bash
 33 | /task:status task-id
 34 | ```
 35 | 
 36 | 表示される情報：
 37 | - 全体の進捗率
 38 | - 完了したサブタスク
 39 | - 現在作業中の項目
 40 | - ブロッカーの有無
 41 | - 残り作業の見積もり
 42 | 
 43 | ### :resume
 44 | 中断したタスクを再開：
 45 | ```bash
 46 | /task:resume task-id
 47 | ```
 48 | 
 49 | 復元される内容：
 50 | - 前回の作業状態
 51 | - 編集中のファイル
 52 | - 実行したコマンド履歴
 53 | - 意思決定の記録
 54 | - テスト結果
 55 | 
 56 | ### :update
 57 | タスクに新しい情報を追加：
 58 | ```bash
 59 | /task:update task-id "ライブラリの競合を発見、代替案を検討中"
 60 | ```
 61 | 
 62 | ### :complete
 63 | タスクを完了としてマーク：
 64 | ```bash
 65 | /task:complete task-id
 66 | ```
 67 | 
 68 | 完了時の処理：
 69 | - 成果物のサマリー生成
 70 | - ドキュメントの自動作成
 71 | - 学習事項の記録
 72 | - アーカイブの作成
 73 | 
 74 | ## タスク構造
 75 | 
 76 | ```yaml
 77 | タスク:
 78 |   ID: task-2024-01-oauth
 79 |   タイトル: OAuth 2.0認証システムの実装
 80 |   状態: in_progress
 81 |   作成日時: 2024-01-15 10:00:00
 82 | 
 83 |   受け入れ条件:
 84 |     - Google/GitHub OAuth対応
 85 |     - リフレッシュトークンの実装
 86 |     - セキュアなトークン保存
 87 | 
 88 |   技術要件:
 89 |     - Python 3.12+
 90 |     - FastAPI
 91 |     - SQLAlchemy
 92 |     - JWT
 93 | 
 94 |   サブタスク:
 95 |     - ID: subtask-1
 96 |       タイトル: OAuthプロバイダー設定
 97 |       状態: completed
 98 |       工数: 2h
 99 | 
100 |     - ID: subtask-2
101 |       タイトル: 認証フローの実装
102 |       状態: in_progress
103 |       工数: 4h
104 |       依存: subtask-1
105 | 
106 |     - ID: subtask-3
107 |       タイトル: トークン管理
108 |       状態: pending
109 |       工数: 3h
110 |       依存: subtask-2
111 | ```
112 | 
113 | ## 自動機能
114 | 
115 | ### スマートな分解
116 | タスクの説明から自動的に：
117 | - 必要な機能を特定
118 | - 技術的な要件を抽出
119 | - 適切な粒度でサブタスク化
120 | - 依存関係を設定
121 | - 現実的な工数を見積もり
122 | 
123 | ### コンテキスト保存
124 | 作業中の情報を自動保存：
125 | - 編集したファイルのリスト
126 | - 実行したコマンド
127 | - テスト結果
128 | - エラーと解決方法
129 | - 意思決定の理由
130 | 
131 | ### 進捗追跡
132 | リアルタイムで更新：
133 | - TodoWriteとの連携
134 | - gitコミットとの紐付け
135 | - テスト結果の記録
136 | - メトリクスの収集
137 | 
138 | ## セッション管理
139 | 
140 | ### 自動復旧
141 | セッションが中断された場合：
142 | 1. 未完了タスクを自動検出
143 | 2. 前回の状態を復元
144 | 3. 作業継続の提案
145 | 
146 | ### 状態の永続化
147 | `.claude/tasks/`ディレクトリに保存：
148 | - タスク定義
149 | - 進捗情報
150 | - コンテキストデータ
151 | - 成果物
152 | 
153 | ## 統合機能
154 | 
155 | ### TodoWriteとの連携
156 | - サブタスクを自動的にTodoWriteに追加
157 | - 進捗を同期
158 | - 完了状態を反映
159 | 
160 | ### Git連携
161 | - コミットメッセージにタスクIDを含める
162 | - ブランチ名の自動生成
163 | - マージ時の自動更新
164 | 
165 | ### テスト連携
166 | - テスト結果をタスクに記録
167 | - カバレッジの追跡
168 | - 品質メトリクスの収集
169 | 
170 | ## ベストプラクティス
171 | 
172 | 1. **明確な説明**: タスク作成時は具体的な要件を記載
173 | 2. **定期的な更新**: 発見や決定事項は都度更新
174 | 3. **小さなコミット**: サブタスク単位でコミット
175 | 4. **テストの維持**: 各サブタスク完了時にテスト実行
176 | 5. **ドキュメント化**: 重要な決定は理由と共に記録
177 | 
178 | ## 出力例
179 | 
180 | ```yaml
181 | タスクサマリー:
182 |   ID: task-2024-01-oauth
183 |   進捗: 65%
184 |   経過時間: 8.5h / 見積もり12h
185 | 
186 | 完了サブタスク:
187 |   ✓ OAuthプロバイダー設定 (2h)
188 |   ✓ 基本認証フロー (3h)
189 |   ✓ データベーススキーマ (1.5h)
190 | 
191 | 作業中:
192 |   → トークンリフレッシュ機能 (2h, 50%完了)
193 | 
194 | 保留中:
195 |   - セキュリティテスト (2h)
196 |   - ドキュメント作成 (1.5h)
197 | 
198 | ブロッカー:
199 |   なし
200 | 
201 | 次のアクション:
202 |   トークンリフレッシュのテストケース作成
203 | ```
204 | 


--------------------------------------------------------------------------------
/.claude/commands/safe-refactor.md:
--------------------------------------------------------------------------------
  1 | # 安全なリファクタリング
  2 | 
  3 | テストカバレッジを維持しながら、コードを安全にリファクタリングします。template/ディレクトリの実装パターンを参考にして、コードの品質と保守性を向上させます。
  4 | 
  5 | ## 基本原則
  6 | 
  7 | 1. **テストが通ることを確認** - リファクタリング前後でテストが通ることを保証
  8 | 2. **小さなステップで進める** - 一度に大きな変更を加えない
  9 | 3. **パターンの参照** - template/ディレクトリの実装例を参考にする
 10 | 4. **コミットの頻度** - 各リファクタリングステップでコミット
 11 | 
 12 | ## リファクタリングの種類と手順
 13 | 
 14 | ### 1. 型安全性の向上
 15 | **参考**: @template/src/template_package/types.py
 16 | 
 17 | ```python
 18 | # Before: 辞書をそのまま使用
 19 | def process_item(item: dict) -> dict:
 20 |     return {"id": item["id"], "processed": True}
 21 | 
 22 | # After: TypedDictを使用
 23 | from typing import TypedDict
 24 | 
 25 | class ItemDict(TypedDict):
 26 |     id: int
 27 |     name: str
 28 |     value: int
 29 | 
 30 | class ProcessedItemDict(ItemDict):
 31 |     processed: bool
 32 | 
 33 | def process_item(item: ItemDict) -> ProcessedItemDict:
 34 |     return {**item, "processed": True}
 35 | ```
 36 | 
 37 | ### 2. エラーハンドリングの改善
 38 | **参考**: @template/src/template_package/core/example.py
 39 | 
 40 | ```python
 41 | # Before: 単純なエラー
 42 | if not data:
 43 |     raise ValueError("Invalid data")
 44 | 
 45 | # After: 具体的で実用的なエラー
 46 | if not data:
 47 |     raise ValueError(
 48 |         f"Data cannot be empty when validation is enabled. "
 49 |         f"Either provide valid data or set validate=False."
 50 |     )
 51 | ```
 52 | 
 53 | ### 3. ロギングの追加
 54 | **参考**: @template/src/template_package/utils/logging_config.py
 55 | 
 56 | ```python
 57 | from project_name.utils.logging_config import get_logger
 58 | 
 59 | logger = get_logger(__name__)
 60 | 
 61 | def process_data(data: list) -> list:
 62 |     logger.debug(f"Processing {len(data)} items")
 63 | 
 64 |     try:
 65 |         result = [transform(item) for item in data]
 66 |         logger.info(f"Successfully processed {len(result)} items")
 67 |         return result
 68 |     except Exception as e:
 69 |         logger.error(f"Failed to process data: {e}", exc_info=True)
 70 |         raise
 71 | ```
 72 | 
 73 | ### 4. テストの追加・改善
 74 | **参考**: @template/tests/
 75 | 
 76 | - 単体テスト: 正常系・異常系・エッジケース
 77 | - プロパティベーステスト: Hypothesisを使用した自動テスト
 78 | - 統合テスト: コンポーネント間の連携
 79 | 
 80 | ### 5. パフォーマンスの最適化
 81 | **参考**: @template/src/template_package/utils/profiling.py
 82 | 
 83 | ```python
 84 | from project_name.utils.profiling import profile, timeit
 85 | 
 86 | @timeit
 87 | def optimized_function(data: list) -> list:
 88 |     # リスト内包表記を使用
 89 |     return [item * 2 for item in data if item > 0]
 90 | 
 91 | @profile
 92 | def heavy_computation():
 93 |     # プロファイリング対象の処理
 94 |     pass
 95 | ```
 96 | 
 97 | ## 実行ステップ
 98 | 
 99 | 1. **現状の確認**
100 |    ```bash
101 |    make test              # テストが通ることを確認
102 |    make test-cov          # カバレッジを記録
103 |    ```
104 | 
105 | 2. **リファクタリング対象の特定**
106 |    - 複雑度の高い関数
107 |    - 重複コード
108 |    - 型安全性が低い箇所
109 |    - エラーハンドリングが不十分な箇所
110 | 
111 | 3. **段階的なリファクタリング**
112 |    - 一つの改善点に集中
113 |    - テストを実行して動作確認
114 |    - コミット（リファクタリング内容を明記）
115 | 
116 | 4. **品質チェック**
117 |    ```bash
118 |    make check-all         # 全体的な品質チェック
119 |    make test-cov          # カバレッジが維持されているか確認
120 |    make benchmark         # パフォーマンスの確認（必要に応じて）
121 |    ```
122 | 
123 | ## リファクタリングのチェックリスト
124 | 
125 | - [ ] 関数は単一責任の原則に従っているか
126 | - [ ] 適切な型ヒントが付けられているか
127 | - [ ] エラーメッセージは具体的で実用的か
128 | - [ ] 適切なロギングが実装されているか
129 | - [ ] テストカバレッジは維持/向上しているか
130 | - [ ] template/の実装パターンに準拠しているか
131 | - [ ] ドキュメント（docstring）は更新されているか
132 | 
133 | ## 注意事項
134 | 
135 | 1. **動作の変更は避ける** - リファクタリングは内部構造の改善であり、外部動作は変えない
136 | 2. **テストファースト** - テストがない場合は先にテストを書く
137 | 3. **段階的コミット** - 大きな変更は小さなコミットに分割
138 | 4. **レビューの準備** - 変更理由を明確に説明できるようにする
139 | 
140 | このコマンドを使用することで、コードベースを継続的に改善し、長期的な保守性を確保できます。
141 | 


--------------------------------------------------------------------------------
/.claude/commands/troubleshoot.md:
--------------------------------------------------------------------------------
  1 | # /troubleshoot - 体系的なデバッグ
  2 | 
  3 | **目的**: 問題の根本原因を特定し、エビデンスベースの解決策を提供
  4 | 
  5 | ## 概要
  6 | 
  7 | `/troubleshoot`コマンドは、エラーや不具合を体系的に分析し、段階的な解決アプローチを提供します。
  8 | 
  9 | ## 使用方法
 10 | 
 11 | ```bash
 12 | /troubleshoot [オプション] [対象/エラーメッセージ]
 13 | ```
 14 | 
 15 | ## オプション
 16 | 
 17 | ### --fix
 18 | 問題の自動修正を試行：
 19 | - 一般的なエラーパターンの認識
 20 | - 安全な修正の自動適用
 21 | - 修正前後の動作確認
 22 | - ロールバック機能
 23 | 
 24 | ### --prod
 25 | 本番環境の問題に対応：
 26 | - 最小限の変更で修正
 27 | - ダウンタイムの最小化
 28 | - 緊急パッチの作成
 29 | - ロールバック計画の提供
 30 | 
 31 | ### --deep
 32 | 深い分析を実行：
 33 | - スタックトレースの完全解析
 34 | - 関連コードの調査
 35 | - 依存関係の追跡
 36 | - 過去の類似問題の検索
 37 | 
 38 | ### --interactive
 39 | 対話的なデバッグ：
 40 | - ステップバイステップの調査
 41 | - 仮説の検証
 42 | - 部分的な修正の試行
 43 | - フィードバックループ
 44 | 
 45 | ## デバッグプロセス
 46 | 
 47 | ### 1. 問題の特定
 48 | ```yaml
 49 | 症状の収集:
 50 |   - エラーメッセージ
 51 |   - 発生条件
 52 |   - 影響範囲
 53 |   - 再現手順
 54 | ```
 55 | 
 56 | ### 2. 原因分析
 57 | ```yaml
 58 | 分析手法:
 59 |   - スタックトレース解析
 60 |   - ログファイル調査
 61 |   - 環境差分の確認
 62 |   - タイミング問題の検証
 63 | ```
 64 | 
 65 | ### 3. 仮説立案
 66 | ```yaml
 67 | 仮説の優先順位:
 68 |   1. 最も可能性が高い原因
 69 |   2. 最も影響が大きい原因
 70 |   3. 最も修正が簡単な原因
 71 | ```
 72 | 
 73 | ### 4. 解決策の実装
 74 | ```yaml
 75 | 修正アプローチ:
 76 |   - 最小限の変更
 77 |   - 段階的な適用
 78 |   - 副作用の確認
 79 |   - テストの追加
 80 | ```
 81 | 
 82 | ## 一般的な問題パターン
 83 | 
 84 | ### 型エラー
 85 | ```python
 86 | # 問題
 87 | TypeError: unsupported operand type(s) for +: 'int' and 'str'
 88 | ```
 89 | 
 90 | ```yaml
 91 | # 診断
 92 | - 型の不一致を検出
 93 | - 変数の型を追跡
 94 | - 型変換の必要性を特定
 95 | 
 96 | # 解決策
 97 | - 明示的な型変換
 98 | - 型ヒントの追加
 99 | - バリデーションの実装
100 | ```
101 | 
102 | ### インポートエラー
103 | ```python
104 | # 問題
105 | ModuleNotFoundError: No module named 'package_name'
106 | ```
107 | 
108 | ```yaml
109 | # 診断
110 | - パッケージの存在確認
111 | - インストール状態の確認
112 | - パスの問題を調査
113 | 
114 | # 解決策
115 | - uv add package_name
116 | - PYTHONPATH の修正
117 | - 仮想環境の確認
118 | ```
119 | 
120 | ### パフォーマンス問題
121 | ```python
122 | # 問題
123 | API response time exceeds 1000ms
124 | ```
125 | 
126 | ```yaml
127 | # 診断
128 | - ボトルネックの特定
129 | - クエリの分析
130 | - メモリ使用量の確認
131 | 
132 | # 解決策
133 | - クエリの最適化
134 | - キャッシングの実装
135 | - 非同期処理の導入
136 | ```
137 | 
138 | ## 実行例
139 | 
140 | ### 基本的な使用
141 | ```bash
142 | # エラーメッセージから診断
143 | /troubleshoot "TypeError: 'NoneType' object is not subscriptable"
144 | 
145 | # 特定ファイルの問題を調査
146 | /troubleshoot --deep src/auth/login.py
147 | 
148 | # 本番環境の緊急対応
149 | /troubleshoot --prod --fix "500 Internal Server Error"
150 | ```
151 | 
152 | ### 高度な使用
153 | ```bash
154 | # 対話的デバッグセッション
155 | /troubleshoot --interactive --deep
156 | 
157 | # パフォーマンス問題の調査
158 | /troubleshoot "Slow query performance" --perf
159 | ```
160 | 
161 | ## 出力形式
162 | 
163 | ```yaml
164 | 診断レポート:
165 |   問題: [エラーの概要]
166 |   重大度: CRITICAL|HIGH|MEDIUM|LOW
167 |   影響範囲: [影響を受ける機能]
168 | 
169 | 根本原因:
170 |   原因: [特定された原因]
171 |   証拠: [原因を裏付けるデータ]
172 |   場所: [ファイル:行番号]
173 | 
174 | 解決策:
175 |   推奨アプローチ: [最適な解決方法]
176 |   実装手順:
177 |     1. [具体的なステップ]
178 |     2. [次のステップ]
179 | 
180 |   代替案:
181 |     - [別の解決方法]
182 |     - [回避策]
183 | 
184 | 検証方法:
185 |   - [修正を確認するテスト]
186 |   - [回帰テスト]
187 | 
188 | 予防策:
189 |   - [同様の問題を防ぐ方法]
190 |   - [監視の追加]
191 | ```
192 | 
193 | ## デバッグ戦略
194 | 
195 | ### Five Whys (なぜなぜ分析)
196 | ```yaml
197 | 症状: APIがタイムアウトする
198 | なぜ1: レスポンスに5秒以上かかる
199 | なぜ2: データベースクエリが遅い
200 | なぜ3: インデックスが不足している
201 | なぜ4: 大量データ投入時に作成されなかった
202 | なぜ5: マイグレーションスクリプトの不備
203 | 
204 | 根本原因: マイグレーションプロセスの改善が必要
205 | ```
206 | 
207 | ### 二分探索デバッグ
208 | ```yaml
209 | 手法: 問題の範囲を半分ずつ絞り込む
210 | 1. 全体の中間点でテスト
211 | 2. 問題がある側を特定
212 | 3. その範囲の中間点でテスト
213 | 4. 問題箇所を特定するまで繰り返し
214 | ```
215 | 
216 | ## 既存ツールとの連携
217 | 
218 | - `make test`: テストによる問題の再現
219 | - `make typecheck`: 型関連の問題確認
220 | - `uv run python -m pdb`: Pythonデバッガーの使用
221 | - `git bisect`: 問題が導入されたコミットの特定
222 | 
223 | ## ベストプラクティス
224 | 
225 | 1. **証拠の収集**: 推測ではなくデータに基づく
226 | 2. **再現性の確保**: 問題を確実に再現できる手順を確立
227 | 3. **段階的アプローチ**: 大きな変更より小さな修正を積み重ねる
228 | 4. **テストの追加**: 修正と同時に回帰テストを作成
229 | 5. **ドキュメント化**: 問題と解決策を記録
230 | 
231 | ## 注意事項
232 | 
233 | - `--fix`オプションは慎重に使用してください
234 | - 本番環境では必ずバックアップを取得してから実行
235 | - 原因が特定できない場合は、より詳細なログを有効化
236 | - パフォーマンス問題は必ず計測してから対処
237 | 


--------------------------------------------------------------------------------
/pyproject.toml:
--------------------------------------------------------------------------------
  1 | [project]
  2 | name = "project-name"
  3 | version = "0.1.0"
  4 | description = "A modern Python project template optimized for Claude Code with strict guardrails"
  5 | readme = "README.md"
  6 | requires-python = ">=3.12"
  7 | dependencies = [
  8 |     "structlog>=25.4.0",
  9 |     "rich>=13.7.0", # for structlog
 10 | ]
 11 | 
 12 | [project.optional-dependencies]
 13 | dev = [
 14 |     "pytest>=8.0.0",
 15 |     "pytest-cov>=5.0.0",
 16 |     "pytest-xdist>=3.5.0",
 17 |     "pytest-benchmark>=5.1.0",
 18 |     "hypothesis>=6.0.0",
 19 |     "pyright>=1.1.389",
 20 |     "ruff>=0.4.0",
 21 |     "pre-commit>=3.7.0",
 22 |     "bandit>=1.7.0",
 23 |     "pip-audit>=2.6.0",
 24 | ]
 25 | 
 26 | docs = [
 27 |     "sphinx>=7.0.0",
 28 |     "sphinx-rtd-theme>=2.0.0",
 29 |     "sphinx-autodoc-typehints>=2.0.0",
 30 |     "myst-parser>=2.0.0",
 31 | ]
 32 | 
 33 | [build-system]
 34 | requires = ["hatchling"]
 35 | build-backend = "hatchling.build"
 36 | 
 37 | [tool.hatch.build.targets.wheel]
 38 | packages = ["src/project_name"]
 39 | 
 40 | [tool.ruff]
 41 | line-length = 88
 42 | indent-width = 4
 43 | target-version = "py312"
 44 | 
 45 | [tool.ruff.lint]
 46 | exclude = [".venv"]
 47 | select = [
 48 |     "E",      # pycodestyle errors
 49 |     "W",      # pycodestyle warnings
 50 |     "F",      # pyflakes
 51 |     "I",      # isort
 52 |     "B",      # flake8-bugbear
 53 |     "SIM",    # flake8-simplify
 54 |     "RUF",    # Ruff-specific rules
 55 |     "TCH",    # flake8-type-checking
 56 |     "PTH",    # flake8-use-pathlib
 57 |     "PL",     # Pylint
 58 | ]
 59 | ignore = [
 60 |     "E501",
 61 |     "B007",
 62 |     "B008",
 63 |     "C401",
 64 |     "C408",
 65 |     "F821",
 66 |     "F841",
 67 |     "G004",
 68 |     "T201",
 69 |     "ANN101",
 70 |     "ANN102",
 71 |     "RUF001",
 72 |     "RUF002",
 73 |     "RUF003",
 74 |     "RUF012",
 75 |     "PTH123",
 76 |     "PERF203",
 77 |     "PERF401",
 78 |     "PLW0603",
 79 |     "PLC0206",
 80 |     "PLC2401",
 81 |     "PLR0911",
 82 |     "PLR0912",
 83 |     "PLR0913",
 84 |     "PLR0915",
 85 |     "PLR2004",
 86 |     "PLW2901",
 87 |     "SIM108",
 88 | ]
 89 | 
 90 | [tool.pyright]
 91 | include = ["src", "tests"]
 92 | exclude = [".venv", "**/__pycache__"]
 93 | pythonVersion = "3.12"
 94 | pythonPlatform = "All"
 95 | typeCheckingMode = "basic"
 96 | 
 97 | # Type checking behavior
 98 | strictParameterNoneValue = false
 99 | 
100 | # 重要なエラー（必ずエラーとして報告）
101 | reportMissingImports = "error"
102 | reportIncompatibleMethodOverride = "error"
103 | reportIncompatibleVariableOverride = "error"
104 | reportOverlappingOverload = "error"
105 | reportUnusedCoroutine = "error"
106 | reportMatchNotExhaustive = "error"
107 | reportUnusedImport = "error"
108 | reportDuplicateImport = "error"
109 | 
110 | # 開発時に役立つ警告レベル
111 | reportUnusedClass = "warning"
112 | reportUnusedFunction = "warning"
113 | reportUnusedVariable = "warning"
114 | reportInconsistentConstructor = "warning"
115 | reportUninitializedInstanceVariable = "warning"
116 | reportUnnecessaryIsInstance = "warning"
117 | reportUnnecessaryCast = "warning"
118 | reportUnnecessaryComparison = "warning"
119 | reportUnnecessaryTypeIgnoreComment = "warning"
120 | 
121 | # 開発を妨げない程度に無効化
122 | reportCallIssue = "none"
123 | reportAttributeAccessIssue = "none"
124 | reportMissingTypeStubs = "none"
125 | reportMissingSuperCall = "none"
126 | reportPrivateUsage = "none"
127 | reportImplicitStringConcatenation = "none"
128 | reportInvalidStubStatement = "none"
129 | reportIncompleteStub = "none"
130 | reportUnsupportedDunderAll = "none"
131 | 
132 | [tool.bandit]
133 | exclude_dirs = ["tests", ".venv"]
134 | skips = ["B101", "B311", "B404", "B603"]
135 | 
136 | [tool.pytest.ini_options]
137 | testpaths = ["tests"]
138 | python_files = ["test_*.py", "*_test.py"]
139 | addopts = [
140 |     "-ra",
141 |     "--strict-markers",
142 |     "--strict-config",
143 |     "--cov-branch",
144 | ]
145 | markers = [
146 |     "slow: marks tests as slow (deselect with '-m \"not slow\"')",
147 |     "integration: marks tests as integration tests",
148 | ]
149 | 
150 | [dependency-groups]
151 | dev = [
152 |     "pyright>=1.1.403",
153 | ]
154 | 


--------------------------------------------------------------------------------
/src/project_name/core/example.py:
--------------------------------------------------------------------------------
  1 | """Example module with basic functionality."""
  2 | 
  3 | from dataclasses import dataclass
  4 | from typing import Any, Protocol
  5 | 
  6 | from ..utils.logging_config import get_logger
  7 | 
  8 | logger = get_logger(__name__)
  9 | 
 10 | 
 11 | @dataclass
 12 | class ExampleConfig:
 13 |     """Configuration for example functionality."""
 14 | 
 15 |     name: str
 16 |     max_items: int = 100
 17 |     enable_validation: bool = True
 18 | 
 19 |     def __post_init__(self) -> None:
 20 |         """Validate configuration after initialization."""
 21 |         if self.max_items <= 0:
 22 |             raise ValueError("max_items must be positive")
 23 | 
 24 | 
 25 | class DataProcessor(Protocol):
 26 |     """Protocol for data processors."""
 27 | 
 28 |     def process(self, data: list[dict[str, Any]]) -> list[dict[str, Any]]:
 29 |         """Process data and return processed result."""
 30 |         ...
 31 | 
 32 | 
 33 | class ExampleClass:
 34 |     """Example class demonstrating the project structure."""
 35 | 
 36 |     def __init__(self, config: ExampleConfig) -> None:
 37 |         """Initialize with configuration."""
 38 |         self.config = config
 39 |         self._items: list[dict[str, Any]] = []
 40 |         logger.info(
 41 |             "ExampleClass initialized",
 42 |             config_name=config.name,
 43 |             max_items=config.max_items,
 44 |         )
 45 | 
 46 |     def add_item(self, item: dict[str, Any]) -> None:
 47 |         """Add an item to the collection."""
 48 |         logger.debug("Adding item", item_id=item.get("id"), item_name=item.get("name"))
 49 | 
 50 |         if len(self._items) >= self.config.max_items:
 51 |             raise ValueError("max_items limit exceeded")
 52 | 
 53 |         if self.config.enable_validation:
 54 |             required_fields = {"id", "name", "value"}
 55 |             if not all(field in item for field in required_fields):
 56 |                 raise ValueError("Missing required fields: id, name, value")
 57 |             if not item.get("name"):
 58 |                 raise ValueError("name cannot be empty")
 59 | 
 60 |         self._items.append(item)
 61 |         logger.debug(
 62 |             "Item added successfully",
 63 |             total_items=len(self._items),
 64 |             max_items=self.config.max_items,
 65 |         )
 66 | 
 67 |     def get_items(
 68 |         self,
 69 |         filter_key: str | None = None,
 70 |         filter_value: Any = None,
 71 |     ) -> list[dict[str, Any]]:
 72 |         """Get items with optional filtering."""
 73 |         logger.debug(
 74 |             "Getting items",
 75 |             filter_key=filter_key,
 76 |             filter_value=filter_value,
 77 |             total_items=len(self._items),
 78 |         )
 79 | 
 80 |         if filter_key is None:
 81 |             return self._items.copy()
 82 | 
 83 |         filtered = [
 84 |             item for item in self._items if item.get(filter_key) == filter_value
 85 |         ]
 86 |         logger.debug(
 87 |             "Items filtered",
 88 |             original_count=len(self._items),
 89 |             filtered_count=len(filtered),
 90 |             filter_key=filter_key,
 91 |         )
 92 |         return filtered
 93 | 
 94 |     def __len__(self) -> int:
 95 |         """Return number of items."""
 96 |         return len(self._items)
 97 | 
 98 |     def __repr__(self) -> str:
 99 |         """Return string representation."""
100 |         return (
101 |             f"ExampleClass(name='{self.config.name}', "
102 |             f"items={len(self._items)}/{self.config.max_items})"
103 |         )
104 | 
105 | 
106 | def process_data(
107 |     data: list[dict[str, Any]],
108 |     processor: DataProcessor,
109 |     validate: bool = True,
110 | ) -> list[dict[str, Any]]:
111 |     """Process data using the provided processor."""
112 |     logger.info("Processing data", item_count=len(data), validation_enabled=validate)
113 | 
114 |     if validate and not data:
115 |         raise ValueError("Data cannot be empty when validation is enabled")
116 | 
117 |     result = processor.process(data)
118 |     logger.info("Processing completed", input_count=len(data), output_count=len(result))
119 |     return result
120 | 


--------------------------------------------------------------------------------
/.claude/commands/scan.md:
--------------------------------------------------------------------------------
  1 | # /scan - セキュリティと品質の包括的検証
  2 | 
  3 | **目的**: プロジェクトのセキュリティ脆弱性と品質問題を検出し、検証する
  4 | 
  5 | ## 概要
  6 | 
  7 | `/scan`コマンドは、コードベース全体をスキャンし、セキュリティリスクと品質問題を特定します。既存のツール（bandit、pip-audit）と連携して包括的な検証を提供します。
  8 | 
  9 | ## 使用方法
 10 | 
 11 | ```bash
 12 | /scan [オプション] [対象]
 13 | ```
 14 | 
 15 | ## オプション
 16 | 
 17 | ### --security
 18 | セキュリティ脆弱性のスキャン：
 19 | - SQLインジェクション
 20 | - XSS（クロスサイトスクリプティング）
 21 | - 安全でない乱数生成
 22 | - ハードコードされた認証情報
 23 | - 不適切な暗号化
 24 | 
 25 | ### --validate
 26 | 品質検証の実行：
 27 | - コーディング規約の遵守
 28 | - 型の一貫性
 29 | - テストカバレッジ
 30 | - ドキュメントの完全性
 31 | - 依存関係の健全性
 32 | 
 33 | ### --owasp
 34 | OWASP Top 10に基づく検証：
 35 | - A01: アクセス制御の不備
 36 | - A02: 暗号化の失敗
 37 | - A03: インジェクション
 38 | - A04: 安全でない設計
 39 | - A05: セキュリティの設定ミス
 40 | - A06: 脆弱で古いコンポーネント
 41 | - A07: 識別と認証の失敗
 42 | - A08: ソフトウェアとデータの整合性の失敗
 43 | - A09: セキュリティログとモニタリングの失敗
 44 | - A10: サーバーサイドリクエストフォージェリ
 45 | 
 46 | ### --fix
 47 | 検出された問題の自動修正：
 48 | - 安全な代替案への置換
 49 | - セキュリティパッチの適用
 50 | - 設定の強化
 51 | - 依存関係の更新
 52 | 
 53 | ## スキャン項目
 54 | 
 55 | ### セキュリティチェック
 56 | 
 57 | ```yaml
 58 | 認証・認可:
 59 |   - パスワードの複雑性
 60 |   - セッション管理
 61 |   - 権限チェック
 62 |   - 多要素認証
 63 | 
 64 | データ保護:
 65 |   - 暗号化の実装
 66 |   - 機密データの処理
 67 |   - PII（個人識別情報）の扱い
 68 |   - データマスキング
 69 | 
 70 | 入力検証:
 71 |   - サニタイゼーション
 72 |   - バリデーション
 73 |   - エスケープ処理
 74 |   - 型チェック
 75 | ```
 76 | 
 77 | ### 品質チェック
 78 | 
 79 | ```yaml
 80 | コード品質:
 81 |   - 循環的複雑度
 82 |   - 重複コード
 83 |   - デッドコード
 84 |   - 未使用の変数/関数
 85 | 
 86 | 保守性:
 87 |   - モジュール結合度
 88 |   - 依存関係の健全性
 89 |   - ドキュメントカバレッジ
 90 |   - テストカバレッジ
 91 | 
 92 | パフォーマンス:
 93 |   - N+1クエリ
 94 |   - 非効率なアルゴリズム
 95 |   - メモリリーク
 96 |   - リソースの適切な解放
 97 | ```
 98 | 
 99 | ## 実行例
100 | 
101 | ### 基本的な使用
102 | ```bash
103 | # セキュリティスキャン
104 | /scan --security
105 | 
106 | # OWASP Top 10チェック
107 | /scan --owasp
108 | 
109 | # 品質検証
110 | /scan --validate
111 | 
112 | # 包括的スキャン
113 | /scan --security --owasp --validate
114 | ```
115 | 
116 | ### 自動修正付き
117 | ```bash
118 | # セキュリティ問題の自動修正
119 | /scan --security --fix
120 | 
121 | # 修正前の確認
122 | /scan --security --fix --dry-run
123 | ```
124 | 
125 | ## 出力形式
126 | 
127 | ```yaml
128 | スキャン結果サマリー:
129 |   スキャン対象: [ファイル数]
130 |   実行時間: [秒]
131 | 
132 | 発見された問題:
133 |   セキュリティ:
134 |     CRITICAL: [件数]
135 |     HIGH: [件数]
136 |     MEDIUM: [件数]
137 |     LOW: [件数]
138 | 
139 |   品質:
140 |     エラー: [件数]
141 |     警告: [件数]
142 |     情報: [件数]
143 | 
144 | 詳細:
145 |   - ID: SEC-001
146 |     重大度: CRITICAL
147 |     カテゴリ: SQLインジェクション
148 |     場所: src/database/query.py:45
149 |     説明: ユーザー入力が直接SQLクエリに使用されています
150 |     証拠: f"SELECT * FROM users WHERE id = {user_id}"
151 |     推奨修正: パラメータ化クエリを使用
152 | 
153 |   - ID: QUA-023
154 |     重大度: HIGH
155 |     カテゴリ: 複雑度
156 |     場所: src/auth/validator.py:120
157 |     説明: 関数の循環的複雑度が15を超えています（測定値: 18）
158 |     推奨修正: 関数を小さな単位に分割
159 | 
160 | コンプライアンス:
161 |   OWASP Top 10: 8/10 合格
162 |   PCI DSS: 該当項目なし
163 |   GDPR: 要対応事項あり
164 | ```
165 | 
166 | ## 既存ツールとの統合
167 | 
168 | `/scan`は以下のツールと連携：
169 | 
170 | ```bash
171 | # セキュリティツール
172 | make security    # banditを実行
173 | make audit       # pip-auditを実行
174 | 
175 | # 品質ツール
176 | make lint        # ruffでリント
177 | make typecheck   # mypyで型チェック
178 | make test-cov    # カバレッジ測定
179 | 
180 | # 統合ワークフロー
181 | /scan --security → make security → make audit → 総合レポート
182 | ```
183 | 
184 | ## カスタムルール
185 | 
186 | プロジェクト固有のルールを`.claude/scan-rules.yml`に定義：
187 | 
188 | ```yaml
189 | custom_rules:
190 |   - id: PROJ-001
191 |     name: API キー検出
192 |     pattern: "api[_-]?key\\s*=\\s*['\"][^'\"]+['\"]"
193 |     severity: CRITICAL
194 |     message: "APIキーがハードコードされています"
195 | 
196 |   - id: PROJ-002
197 |     name: デバッグコード検出
198 |     pattern: "print\\(|console\\.log\\("
199 |     severity: MEDIUM
200 |     message: "デバッグ用の出力が残っています"
201 | ```
202 | 
203 | ## 除外設定
204 | 
205 | 特定のファイルやパターンを除外：
206 | 
207 | ```yaml
208 | # .claude/scan-ignore.yml
209 | ignore:
210 |   files:
211 |     - "tests/**"
212 |     - "*.test.py"
213 | 
214 |   rules:
215 |     - SEC-001  # 特定のルールを無効化
216 | 
217 |   patterns:
218 |     - "# nosec"  # コメントによる除外
219 | ```
220 | 
221 | ## ベストプラクティス
222 | 
223 | 1. **定期的な実行**: 日次または週次でスキャンを実行
224 | 2. **CI/CD統合**: PRごとに自動スキャン
225 | 3. **段階的改善**: 重大度の高い問題から対処
226 | 4. **False Positive対応**: 誤検出は適切に除外設定
227 | 5. **継続的な更新**: ルールとパターンの定期的な見直し
228 | 
229 | ## 注意事項
230 | 
231 | - スキャンは補完的なツールであり、専門的なセキュリティ監査の代替ではありません
232 | - `--fix`オプションは必ず変更内容を確認してから適用してください
233 | - 大規模なコードベースではスキャンに時間がかかる場合があります
234 | - カスタムルールは慎重にテストしてから本番環境で使用してください
235 | 


--------------------------------------------------------------------------------
/src/project_name/utils/helpers.py:
--------------------------------------------------------------------------------
  1 | """Helper functions for common operations."""
  2 | 
  3 | import json
  4 | from pathlib import Path
  5 | from typing import Any
  6 | 
  7 | from .logging_config import get_logger
  8 | 
  9 | logger = get_logger(__name__)
 10 | 
 11 | 
 12 | def chunk_list(items: list[Any], chunk_size: int) -> list[list[Any]]:
 13 |     """Split a list into chunks of specified size.
 14 | 
 15 |     Parameters
 16 |     ----------
 17 |     items : list[Any]
 18 |         List to be chunked
 19 |     chunk_size : int
 20 |         Size of each chunk (must be positive)
 21 | 
 22 |     Returns
 23 |     -------
 24 |     list[list[Any]]
 25 |         List of chunks
 26 | 
 27 |     Raises
 28 |     ------
 29 |     ValueError
 30 |         If chunk_size is not positive
 31 |     """
 32 |     logger.debug("Chunking list", item_count=len(items), chunk_size=chunk_size)
 33 | 
 34 |     if chunk_size <= 0:
 35 |         raise ValueError("Chunk size must be positive")
 36 | 
 37 |     if not items:
 38 |         logger.debug("Empty list provided, returning empty result")
 39 |         return []
 40 | 
 41 |     chunks = []
 42 |     for i in range(0, len(items), chunk_size):
 43 |         chunk = items[i : i + chunk_size]
 44 |         chunks.append(chunk)
 45 | 
 46 |     logger.debug("Created chunks", chunk_count=len(chunks), item_count=len(items))
 47 |     return chunks
 48 | 
 49 | 
 50 | def flatten_dict(
 51 |     nested_dict: dict[str, Any], separator: str = ".", prefix: str = ""
 52 | ) -> dict[str, Any]:
 53 |     """Flatten a nested dictionary.
 54 | 
 55 |     Parameters
 56 |     ----------
 57 |     nested_dict : dict[str, Any]
 58 |         Dictionary to flatten
 59 |     separator : str, default="."
 60 |         Separator to use between nested keys
 61 |     prefix : str, default=""
 62 |         Prefix to add to all keys
 63 | 
 64 |     Returns
 65 |     -------
 66 |     dict[str, Any]
 67 |         Flattened dictionary
 68 |     """
 69 |     logger.debug(
 70 |         "Flattening dictionary",
 71 |         top_level_keys=len(nested_dict),
 72 |         separator=separator,
 73 |     )
 74 | 
 75 |     result = {}
 76 | 
 77 |     for key, value in nested_dict.items():
 78 |         new_key = f"{prefix}{separator}{key}" if prefix else key
 79 | 
 80 |         if isinstance(value, dict):
 81 |             # Recursively flatten nested dictionaries
 82 |             result.update(flatten_dict(value, separator, new_key))
 83 |         else:
 84 |             result[new_key] = value
 85 | 
 86 |     logger.debug(
 87 |         "Dictionary flattened",
 88 |         original_keys=len(nested_dict),
 89 |         flattened_keys=len(result),
 90 |     )
 91 |     return result
 92 | 
 93 | 
 94 | def save_json_file(data: Any, file_path: str | Path, indent: int | None = 2) -> None:
 95 |     """Save data to a JSON file.
 96 | 
 97 |     Parameters
 98 |     ----------
 99 |     data : Any
100 |         Data to save (must be JSON serializable)
101 |     file_path : str | Path
102 |         Path to save the file
103 |     indent : int | None, default=2
104 |         JSON indentation level
105 | 
106 |     Raises
107 |     ------
108 |     ValueError
109 |         If data is not JSON serializable
110 |     """
111 |     path = Path(file_path)
112 |     logger.debug("Saving JSON data", file_path=str(path), indent=indent)
113 | 
114 |     try:
115 |         path.parent.mkdir(parents=True, exist_ok=True)
116 |         with path.open("w", encoding="utf-8") as f:
117 |             json.dump(data, f, indent=indent, ensure_ascii=False)
118 |         logger.debug("Successfully saved JSON", file_path=str(path))
119 |     except (TypeError, ValueError) as e:
120 |         raise ValueError(f"Data is not JSON serializable: {e}") from e
121 | 
122 | 
123 | def load_json_file(file_path: str | Path) -> Any:
124 |     """Load data from a JSON file.
125 | 
126 |     Parameters
127 |     ----------
128 |     file_path : str | Path
129 |         Path to the JSON file
130 | 
131 |     Returns
132 |     -------
133 |     Any
134 |         Loaded data
135 | 
136 |     Raises
137 |     ------
138 |     FileNotFoundError
139 |         If file does not exist
140 |     ValueError
141 |         If file contains invalid JSON
142 |     """
143 |     path = Path(file_path)
144 |     logger.debug("Loading JSON data", file_path=str(path))
145 | 
146 |     if not path.exists():
147 |         raise FileNotFoundError(f"JSON file not found: {path}")
148 | 
149 |     try:
150 |         with path.open("r", encoding="utf-8") as f:
151 |             data = json.load(f)
152 |         logger.debug("Successfully loaded JSON", file_path=str(path))
153 |         return data
154 |     except json.JSONDecodeError as e:
155 |         raise ValueError(f"Invalid JSON in file {path}: {e}") from e
156 | 


--------------------------------------------------------------------------------
/.github/workflows/ci.yml:
--------------------------------------------------------------------------------
  1 | name: CI
  2 | 
  3 | on:
  4 |   push:
  5 |     branches: [main, develop]
  6 |   pull_request:
  7 |     branches: [main]
  8 |     types: [opened, synchronize, reopened]
  9 |   # 毎週月曜日の朝に定期実行
 10 |   schedule:
 11 |     - cron: '0 0 * * 1'
 12 |   # 手動実行を許可
 13 |   workflow_dispatch:
 14 | 
 15 | # 同じワークフローの同時実行を制御
 16 | concurrency:
 17 |   group: ${{ github.workflow }}-${{ github.ref }}
 18 |   cancel-in-progress: true
 19 | 
 20 | env:
 21 |   PYTHON_VERSION: "3.12"
 22 |   UV_CACHE_DIR: /tmp/.uv-cache
 23 | 
 24 | jobs:
 25 |   lint:
 26 |     name: Lint
 27 |     runs-on: ubuntu-latest
 28 |     steps:
 29 |     - uses: actions/checkout@v4
 30 |       with:
 31 |         fetch-depth: 0  # full history for better blame info
 32 | 
 33 |     - name: Install uv
 34 |       uses: astral-sh/setup-uv@v6
 35 |       with:
 36 |         enable-cache: true
 37 |         cache-dependency-glob: "uv.lock"
 38 | 
 39 |     - name: Set up Python
 40 |       run: uv python pin ${{ env.PYTHON_VERSION }}
 41 | 
 42 |     - name: Install dependencies
 43 |       run: uv sync --all-extras
 44 | 
 45 |     - name: Run pre-commit
 46 |       run: uv run pre-commit run --all-files
 47 | 
 48 |     - name: Check for security issues
 49 |       run: |
 50 |         uv run pip-audit
 51 |         uv run bandit -r src/
 52 | 
 53 |   type-check:
 54 |     name: Type Check
 55 |     runs-on: ubuntu-latest
 56 |     steps:
 57 |     - uses: actions/checkout@v4
 58 | 
 59 |     - name: Install uv
 60 |       uses: astral-sh/setup-uv@v6
 61 |       with:
 62 |         enable-cache: true
 63 |         cache-dependency-glob: "uv.lock"
 64 | 
 65 |     - name: Set up Python
 66 |       run: uv python pin ${{ env.PYTHON_VERSION }}
 67 | 
 68 |     - name: Install dependencies
 69 |       run: uv sync --all-extras
 70 | 
 71 |     - name: Run pyright
 72 |       run: uv run pyright
 73 | 
 74 |   test:
 75 |     name: Test Python ${{ matrix.python-version }} on ${{ matrix.os }}
 76 |     runs-on: ${{ matrix.os }}
 77 |     strategy:
 78 |       fail-fast: false
 79 |       matrix:
 80 |         python-version: ["3.12"]
 81 |         os: [ubuntu-latest]
 82 | 
 83 |     steps:
 84 |     - uses: actions/checkout@v4
 85 | 
 86 |     - name: Install uv
 87 |       uses: astral-sh/setup-uv@v6
 88 |       with:
 89 |         enable-cache: true
 90 |         cache-dependency-glob: "uv.lock"
 91 | 
 92 |     - name: Set up Python ${{ matrix.python-version }}
 93 |       run: uv python pin ${{ matrix.python-version }}
 94 | 
 95 |     - name: Install dependencies
 96 |       run: uv sync --all-extras
 97 | 
 98 |     - name: Run tests
 99 |       run: |
100 |         uv run pytest tests/ \
101 |           --cov=src/project_name \
102 |           --cov-report=xml \
103 |           --cov-report=term-missing \
104 |           --cov-report=html \
105 |           --junit-xml=test-results.xml \
106 |           -v
107 | 
108 |     - name: Upload test results
109 |       if: always()
110 |       uses: actions/upload-artifact@v4
111 |       with:
112 |         name: test-results-${{ matrix.os }}-${{ matrix.python-version }}
113 |         path: test-results.xml
114 | 
115 |     # オプション: カバレッジレポートのアップロード
116 |     # - name: Upload coverage reports
117 |     #   uses: codecov/codecov-action@v4
118 |     #   with:
119 |     #     file: ./coverage.xml
120 |     #     flags: unittests
121 |     #     name: ${{ matrix.os }}-${{ matrix.python-version }}
122 |     #     fail_ci_if_error: false  # カバレッジサービスの問題でCIを失敗させない
123 | 
124 |   # オプション: パッケージのビルド
125 |   # build:
126 |   #   name: Build Distribution
127 |   #   needs: [lint, type-check, test]
128 |   #   runs-on: ubuntu-latest
129 |   #   steps:
130 |   #   - uses: actions/checkout@v4
131 | 
132 |   #   - name: Install uv
133 |   #     uses: astral-sh/setup-uv@v3
134 | 
135 |   #   - name: Build package
136 |   #     run: uv build
137 | 
138 |   #   - name: Check built distributions
139 |   #     run: |
140 |   #       uv run twine check dist/*
141 |   #       ls -la dist/
142 | 
143 |   #   - name: Upload distributions
144 |   #     uses: actions/upload-artifact@v4
145 |   #     with:
146 |   #       name: dist
147 |   #       path: dist/
148 | 
149 |   # オプション: ドキュメントのビルド
150 |   # docs:
151 |   #   name: Build Documentation
152 |   #   runs-on: ubuntu-latest
153 |   #   steps:
154 |   #   - uses: actions/checkout@v4
155 | 
156 |   #   - name: Install uv
157 |   #     uses: astral-sh/setup-uv@v3
158 |   #     with:
159 |   #       enable-cache: true
160 | 
161 |   #   - name: Set up Python
162 |   #     run: uv python pin ${{ env.PYTHON_VERSION }}
163 | 
164 |   #   - name: Install dependencies
165 |   #     run: |
166 |   #       uv sync --all-extras
167 |   #       uv add sphinx sphinx-rtd-theme sphinx-autodoc-typehints
168 | 
169 |   #   - name: Build docs
170 |   #     run: |
171 |   #       uv run sphinx-build -b html docs/ docs/_build/html
172 | 
173 |   #   - name: Upload docs
174 |   #     uses: actions/upload-artifact@v4
175 |   #     with:
176 |   #       name: docs
177 |   #       path: docs/_build/html/
178 | 
179 |   # すべてのジョブが成功したかチェック（branch protectionで使用）
180 |   all-checks:
181 |     name: All Checks Passed
182 |     runs-on: ubuntu-latest
183 |     needs: [
184 |       lint,
185 |       type-check,
186 |       test,
187 |       # build,
188 |       # docs
189 |     ]
190 |     if: always()
191 |     steps:
192 |       - name: Decide whether the all jobs succeeded
193 |         uses: re-actors/alls-green@release/v1
194 |         with:
195 |           jobs: ${{ toJSON(needs) }}
196 | 


--------------------------------------------------------------------------------
/scripts/update_project_name.py:
--------------------------------------------------------------------------------
  1 | """Update project name throughout the template."""
  2 | 
  3 | import argparse
  4 | import re
  5 | import sys
  6 | from pathlib import Path
  7 | 
  8 | 
  9 | def validate_project_name(name: str) -> bool:
 10 |     """Validate that the project name follows Python package naming conventions."""
 11 |     if not re.match(r"^[a-z][a-z0-9_]*$", name):
 12 |         return False
 13 | 
 14 |     # Check it's not a Python keyword or builtin
 15 |     import builtins
 16 |     import keyword
 17 | 
 18 |     if keyword.iskeyword(name):
 19 |         return False
 20 | 
 21 |     return not hasattr(builtins, name)
 22 | 
 23 | 
 24 | def get_files_to_update() -> list[Path]:
 25 |     """Get list of files that need project name updates."""
 26 |     files = [
 27 |         "pyproject.toml",
 28 |         "README.md",
 29 |     ]
 30 | 
 31 |     # Add optional files if they exist
 32 |     optional_files = [
 33 |         ".github/workflows/ci.yml",
 34 |     ]
 35 | 
 36 |     all_files = files + optional_files
 37 |     return [Path(f) for f in all_files if Path(f).exists()]
 38 | 
 39 | 
 40 | def get_replacements(old_name: str, new_name: str) -> list[tuple[str, str]]:
 41 |     """Get list of string replacements to make."""
 42 |     # Handle both underscore and hyphen versions
 43 |     old_hyphen = old_name.replace("_", "-")
 44 |     new_hyphen = new_name.replace("_", "-")
 45 | 
 46 |     return [
 47 |         # Exact matches
 48 |         (old_name, new_name),
 49 |         (old_hyphen, new_hyphen),
 50 |         # In quotes
 51 |         (f'"{old_name}"', f'"{new_name}"'),
 52 |         (f'"{old_hyphen}"', f'"{new_hyphen}"'),
 53 |         (f"'{old_name}'", f"'{new_name}'"),
 54 |         (f"'{old_hyphen}'", f"'{new_hyphen}'"),
 55 |         # Import statements
 56 |         (f"from {old_name}", f"from {new_name}"),
 57 |         (f"import {old_name}", f"import {new_name}"),
 58 |         # Markdown code blocks
 59 |         (f"`{old_name}`", f"`{new_name}`"),
 60 |         (f"`{old_hyphen}`", f"`{new_hyphen}`"),
 61 |     ]
 62 | 
 63 | 
 64 | def update_file_contents(file_path: Path, replacements: list[tuple[str, str]]) -> bool:
 65 |     """Update file contents with replacements."""
 66 |     try:
 67 |         content = file_path.read_text(encoding="utf-8")
 68 |         original_content = content
 69 | 
 70 |         for old, new in replacements:
 71 |             content = content.replace(old, new)
 72 | 
 73 |         if content != original_content:
 74 |             file_path.write_text(content, encoding="utf-8")
 75 |             return True
 76 | 
 77 |         return False
 78 |     except Exception as e:
 79 |         print(f"Error updating {file_path}: {e}", file=sys.stderr)
 80 |         return False
 81 | 
 82 | 
 83 | def rename_directory(old_name: str, new_name: str) -> bool:
 84 |     """Rename the package directory."""
 85 |     old_dir = Path(f"src/{old_name}")
 86 |     new_dir = Path(f"src/{new_name}")
 87 | 
 88 |     if old_dir.exists() and not new_dir.exists():
 89 |         try:
 90 |             old_dir.rename(new_dir)
 91 |             print(f"✓ Renamed directory: {old_dir} → {new_dir}")
 92 |             return True
 93 |         except Exception as e:
 94 |             print(f"Error renaming directory: {e}", file=sys.stderr)
 95 |             return False
 96 | 
 97 |     return False
 98 | 
 99 | 
100 | def main() -> None:
101 |     """Main function."""
102 |     parser = argparse.ArgumentParser(
103 |         description="Update project name throughout the template"
104 |     )
105 |     parser.add_argument(
106 |         "new_name",
107 |         help="New project name (lowercase, underscores allowed)",
108 |     )
109 |     parser.add_argument(
110 |         "--old-name",
111 |         default="project_name",
112 |         help="Old project name to replace (default: project_name)",
113 |     )
114 |     parser.add_argument(
115 |         "--dry-run",
116 |         action="store_true",
117 |         help="Show what would be changed without making changes",
118 |     )
119 | 
120 |     args = parser.parse_args()
121 | 
122 |     # Validate new name
123 |     if not validate_project_name(args.new_name):
124 |         print(f"Error: '{args.new_name}' is not a valid Python package name.")
125 |         print("Package names must:")
126 |         print("  - Start with a lowercase letter")
127 |         print("  - Contain only lowercase letters, numbers, and underscores")
128 |         print("  - Not be a Python keyword or builtin")
129 |         sys.exit(1)
130 | 
131 |     if args.new_name == args.old_name:
132 |         print("New name is the same as old name. Nothing to do.")
133 |         sys.exit(0)
134 | 
135 |     print(f"Updating project name: {args.old_name} → {args.new_name}")
136 | 
137 |     # Get replacements
138 |     replacements = get_replacements(args.old_name, args.new_name)
139 | 
140 |     # Update files
141 |     files = get_files_to_update()
142 |     updated_count = 0
143 | 
144 |     for file_path in files:
145 |         if args.dry_run:
146 |             content = file_path.read_text(encoding="utf-8")
147 |             would_change = any(old in content for old, _ in replacements)
148 |             if would_change:
149 |                 print(f"Would update: {file_path}")
150 |         elif update_file_contents(file_path, replacements):
151 |             print(f"✓ Updated: {file_path}")
152 |             updated_count += 1
153 | 
154 |     # Rename directory
155 |     if args.dry_run:
156 |         old_dir = Path(f"src/{args.old_name}")
157 |         if old_dir.exists():
158 |             print(f"Would rename: {old_dir} → src/{args.new_name}")
159 |     elif rename_directory(args.old_name, args.new_name):
160 |         updated_count += 1
161 | 
162 |     # Summary
163 |     if args.dry_run:
164 |         print("\nDry run complete. No files were modified.")
165 |     else:
166 |         print(f"\n✨ Updated {updated_count} items successfully!")
167 | 
168 |         # Additional instructions
169 |         print("\nDon't forget to:")
170 |         print("  1. Update author information in pyproject.toml")
171 |         print("  2. Update the project description in README.md")
172 |         print("  3. Review and update CLAUDE.md if needed")
173 | 
174 | 
175 | if __name__ == "__main__":
176 |     main()
177 | 


--------------------------------------------------------------------------------
/template/tests/unit/test_example.py:
--------------------------------------------------------------------------------
  1 | """Unit tests for example module."""
  2 | 
  3 | from typing import Any
  4 | 
  5 | import pytest
  6 | from template_package.core.example import (
  7 |     ExampleClass,
  8 |     ExampleConfig,
  9 |     process_data,
 10 | )
 11 | 
 12 | 
 13 | class TestExampleConfig:
 14 |     """Test ExampleConfig class."""
 15 | 
 16 |     def test_正常系_デフォルト値で初期化される(self) -> None:
 17 |         """デフォルト値でConfigが作成されることを確認。"""
 18 |         config = ExampleConfig(name="test")
 19 | 
 20 |         assert config.name == "test"
 21 |         assert config.max_items == 100
 22 |         assert config.enable_validation is True
 23 | 
 24 |     def test_正常系_カスタム値で初期化される(self) -> None:
 25 |         """カスタム値でConfigが作成されることを確認。"""
 26 |         config = ExampleConfig(
 27 |             name="custom",
 28 |             max_items=50,
 29 |             enable_validation=False,
 30 |         )
 31 | 
 32 |         assert config.name == "custom"
 33 |         assert config.max_items == 50
 34 |         assert config.enable_validation is False
 35 | 
 36 |     def test_異常系_max_itemsが負の値でValueError(self) -> None:
 37 |         """max_itemsが負の値の場合、ValueErrorが発生することを確認。"""
 38 |         with pytest.raises(ValueError, match="max_items must be positive"):
 39 |             ExampleConfig(name="test", max_items=-1)
 40 | 
 41 |     def test_異常系_max_itemsがゼロでValueError(self) -> None:
 42 |         """max_itemsが0の場合、ValueErrorが発生することを確認。"""
 43 |         with pytest.raises(ValueError, match="max_items must be positive"):
 44 |             ExampleConfig(name="test", max_items=0)
 45 | 
 46 | 
 47 | class TestExampleClass:
 48 |     """Test ExampleClass."""
 49 | 
 50 |     def test_正常系_初期化時は空のリスト(
 51 |         self,
 52 |         example_instance: ExampleClass,
 53 |     ) -> None:
 54 |         """初期化時にデータが空であることを確認。"""
 55 |         assert len(example_instance) == 0
 56 |         assert example_instance.get_items() == []
 57 | 
 58 |     def test_正常系_アイテムを追加できる(
 59 |         self,
 60 |         example_instance: ExampleClass,
 61 |     ) -> None:
 62 |         """アイテムを正常に追加できることを確認。"""
 63 |         item = {"id": 1, "name": "test_item", "value": 42}
 64 |         example_instance.add_item(item)
 65 | 
 66 |         assert len(example_instance) == 1
 67 |         assert example_instance.get_items() == [item]
 68 | 
 69 |     def test_正常系_複数のアイテムを追加できる(
 70 |         self,
 71 |         example_instance: ExampleClass,
 72 |         sample_data: list[dict[str, Any]],
 73 |     ) -> None:
 74 |         """複数のアイテムを追加できることを確認。"""
 75 |         for item in sample_data:
 76 |             example_instance.add_item(item)
 77 | 
 78 |         assert len(example_instance) == len(sample_data)
 79 |         assert example_instance.get_items() == sample_data
 80 | 
 81 |     def test_正常系_フィルタリングが機能する(
 82 |         self,
 83 |         example_instance: ExampleClass,
 84 |         sample_data: list[dict[str, Any]],
 85 |     ) -> None:
 86 |         """フィルタリングが正しく機能することを確認。"""
 87 |         for item in sample_data:
 88 |             example_instance.add_item(item)
 89 | 
 90 |         filtered = example_instance.get_items(
 91 |             filter_key="value",
 92 |             filter_value=200,
 93 |         )
 94 | 
 95 |         assert len(filtered) == 1
 96 |         assert filtered[0]["id"] == 2
 97 | 
 98 |     def test_異常系_最大数を超えるとValueError(
 99 |         self,
100 |         example_config: ExampleConfig,
101 |     ) -> None:
102 |         """最大数を超えてアイテムを追加しようとするとエラーになることを確認。"""
103 |         example_config.max_items = 2
104 |         instance = ExampleClass(example_config)
105 | 
106 |         instance.add_item({"id": 1, "name": "item1", "value": 10})
107 |         instance.add_item({"id": 2, "name": "item2", "value": 20})
108 | 
109 |         with pytest.raises(ValueError, match="max_items limit"):
110 |             instance.add_item({"id": 3, "name": "item3", "value": 30})
111 | 
112 |     def test_異常系_空の辞書でValueError(
113 |         self,
114 |         example_instance: ExampleClass,
115 |     ) -> None:
116 |         """空の辞書を追加しようとするとエラーになることを確認。"""
117 |         with pytest.raises(ValueError, match="Missing required fields"):
118 |             example_instance.add_item({})
119 | 
120 |     def test_異常系_辞書以外を追加しようとするとTypeError(
121 |         self,
122 |         example_instance: ExampleClass,
123 |     ) -> None:
124 |         """辞書以外を追加しようとするとエラーになることを確認。"""
125 |         # mypyによる型チェックがあるため、実行時には型エラーとして扱われる
126 |         # ここでは実際に文字列が渡された場合の動作をテスト
127 |         with pytest.raises((TypeError, AttributeError)):
128 |             example_instance.add_item("not a dict")  # type: ignore
129 | 
130 |     def test_正常系_バリデーション無効時は空の辞書も追加できる(
131 |         self,
132 |         example_config: ExampleConfig,
133 |     ) -> None:
134 |         """バリデーション無効時は制約がないことを確認。"""
135 |         example_config.enable_validation = False
136 |         instance = ExampleClass(example_config)
137 | 
138 |         # バリデーション無効時は空の辞書も追加可能
139 |         instance.add_item({})
140 |         assert len(instance) == 1
141 | 
142 |     def test_正常系_repr表現が正しい(
143 |         self,
144 |         example_instance: ExampleClass,
145 |         sample_data: list[dict[str, Any]],
146 |     ) -> None:
147 |         """repr表現が期待通りであることを確認。"""
148 |         for item in sample_data[:2]:
149 |             example_instance.add_item(item)
150 | 
151 |         repr_str = repr(example_instance)
152 |         assert "ExampleClass" in repr_str
153 |         assert "name='test'" in repr_str
154 |         assert "items=2/10" in repr_str
155 | 
156 | 
157 | class MockProcessor:
158 |     """Mock implementation of DataProcessor protocol."""
159 | 
160 |     def process(self, data: list[dict[str, Any]]) -> list[dict[str, Any]]:
161 |         """Simply return the data with 'processed' flag."""
162 |         return [{**item, "processed": True} for item in data]
163 | 
164 | 
165 | class TestProcessData:
166 |     """Test process_data function."""
167 | 
168 |     def test_正常系_データが処理される(
169 |         self,
170 |         sample_data: list[dict[str, Any]],
171 |     ) -> None:
172 |         """データが正しく処理されることを確認。"""
173 |         processor = MockProcessor()
174 |         result = process_data(sample_data, processor)
175 | 
176 |         assert len(result) == len(sample_data)
177 |         assert all(item["processed"] is True for item in result)
178 | 
179 |     def test_異常系_バリデーション有効で空データはエラー(self) -> None:
180 |         """バリデーション有効時、空データでエラーになることを確認。"""
181 |         processor = MockProcessor()
182 | 
183 |         with pytest.raises(ValueError, match="Data cannot be empty"):
184 |             process_data([], processor, validate=True)
185 | 
186 |     def test_正常系_バリデーション無効で空データも処理できる(self) -> None:
187 |         """バリデーション無効時、空データも処理できることを確認。"""
188 |         processor = MockProcessor()
189 |         result = process_data([], processor, validate=False)
190 | 
191 |         assert result == []
192 | 
193 |     @pytest.mark.parametrize(
194 |         "input_data,expected_length",
195 |         [
196 |             ([{"id": 1}], 1),
197 |             ([{"id": 1}, {"id": 2}], 2),
198 |             ([{"id": i} for i in range(10)], 10),
199 |         ],
200 |     )
201 |     def test_パラメトライズ_様々なサイズのデータを処理できる(
202 |         self,
203 |         input_data: list[dict[str, Any]],
204 |         expected_length: int,
205 |     ) -> None:
206 |         """様々なサイズのデータを処理できることを確認。"""
207 |         processor = MockProcessor()
208 |         result = process_data(input_data, processor)
209 | 
210 |         assert len(result) == expected_length
211 | 


--------------------------------------------------------------------------------
/template/tests/property/test_helpers_property.py:
--------------------------------------------------------------------------------
  1 | """Property-based tests for helper functions using Hypothesis."""
  2 | 
  3 | import tempfile
  4 | from pathlib import Path
  5 | 
  6 | from hypothesis import given
  7 | from hypothesis import strategies as st
  8 | from template_package.utils.helpers import (
  9 |     chunk_list,
 10 |     flatten_dict,
 11 |     load_json_file,
 12 |     save_json_file,
 13 | )
 14 | 
 15 | 
 16 | class TestChunkListProperty:
 17 |     """Property-based tests for chunk_list function."""
 18 | 
 19 |     @given(
 20 |         items=st.lists(st.integers()),
 21 |         chunk_size=st.integers(min_value=1, max_value=100),
 22 |     )
 23 |     def test_プロパティ_チャンク化しても全要素が保持される(
 24 |         self,
 25 |         items: list[int],
 26 |         chunk_size: int,
 27 |     ) -> None:
 28 |         """チャンク化前後で全要素が保持されることを検証。"""
 29 |         chunks = chunk_list(items, chunk_size)
 30 | 
 31 |         # フラット化して元のリストと比較
 32 |         flattened = [item for chunk in chunks for item in chunk]
 33 | 
 34 |         assert flattened == items
 35 | 
 36 |     @given(
 37 |         items=st.lists(st.integers(), min_size=1),
 38 |         chunk_size=st.integers(min_value=1, max_value=100),
 39 |     )
 40 |     def test_プロパティ_各チャンクサイズが適切(
 41 |         self,
 42 |         items: list[int],
 43 |         chunk_size: int,
 44 |     ) -> None:
 45 |         """各チャンクのサイズが期待通りであることを検証。"""
 46 |         chunks = chunk_list(items, chunk_size)
 47 | 
 48 |         if chunks:
 49 |             # 最後のチャンク以外はすべてchunk_sizeと同じ
 50 |             for chunk in chunks[:-1]:
 51 |                 assert len(chunk) == chunk_size
 52 | 
 53 |             # 最後のチャンクは1以上chunk_size以下
 54 |             assert 1 <= len(chunks[-1]) <= chunk_size
 55 | 
 56 |     @given(
 57 |         items=st.lists(st.text(), min_size=0, max_size=1000),
 58 |         chunk_size=st.integers(min_value=1, max_value=100),
 59 |     )
 60 |     def test_プロパティ_チャンク数が正しい(
 61 |         self,
 62 |         items: list[str],
 63 |         chunk_size: int,
 64 |     ) -> None:
 65 |         """チャンク数が数学的に正しいことを検証。"""
 66 |         chunks = chunk_list(items, chunk_size)
 67 | 
 68 |         expected_chunks = (len(items) + chunk_size - 1) // chunk_size
 69 |         if len(items) == 0:
 70 |             expected_chunks = 0
 71 | 
 72 |         assert len(chunks) == expected_chunks
 73 | 
 74 | 
 75 | class TestFlattenDictProperty:
 76 |     """Property-based tests for flatten_dict function."""
 77 | 
 78 |     # JSON互換の値を生成する戦略
 79 |     json_value = st.recursive(
 80 |         st.none()
 81 |         | st.booleans()
 82 |         | st.integers()
 83 |         | st.floats(allow_nan=False)
 84 |         | st.text(),
 85 |         lambda children: st.lists(children, max_size=5)
 86 |         | st.dictionaries(st.text(), children, max_size=5),
 87 |         max_leaves=20,
 88 |     )
 89 | 
 90 |     @given(nested=st.dictionaries(st.text(min_size=1), json_value, max_size=10))
 91 |     def test_プロパティ_フラット化後も全ての値が保持される(
 92 |         self,
 93 |         nested: dict,
 94 |     ) -> None:
 95 |         """フラット化前後で全ての値が保持されることを検証。"""
 96 |         flattened = flatten_dict(nested)
 97 | 
 98 |         # 全ての値を収集
 99 |         def collect_values(d: dict) -> list:
100 |             values = []
101 |             for v in d.values():
102 |                 if isinstance(v, dict):
103 |                     values.extend(collect_values(v))
104 |                 else:
105 |                     values.append(v)
106 |             return values
107 | 
108 |         original_values = sorted(collect_values(nested), key=str)
109 |         flattened_values = sorted(flattened.values(), key=str)
110 | 
111 |         # Noneとリストを含む場合は値の比較が複雑になるため、
112 |         # 少なくとも値の数は同じであることを確認
113 |         assert len(original_values) == len(flattened_values)
114 | 
115 |     @given(
116 |         nested=st.dictionaries(
117 |             st.text(min_size=1, alphabet=st.characters(blacklist_characters=".")),
118 |             st.integers(),
119 |             max_size=10,
120 |         ),
121 |         separator=st.sampled_from([".", "_", "-", "/"]),
122 |     )
123 |     def test_プロパティ_カスタムセパレータが正しく使用される(
124 |         self,
125 |         nested: dict,
126 |         separator: str,
127 |     ) -> None:
128 |         """指定したセパレータが全てのキーで使用されることを検証。"""
129 |         # ネストした構造を作成
130 |         nested_dict = {"level1": nested}
131 | 
132 |         flattened = flatten_dict(nested_dict, separator=separator)
133 | 
134 |         # セパレータが含まれるキーがあることを確認
135 |         if nested and flattened:
136 |             separator_keys = [k for k in flattened if separator in k]
137 |             assert len(separator_keys) > 0
138 | 
139 |             # 他のセパレータが使われていないことを確認
140 |             other_separators = {".", "_", "-", "/"} - {separator}
141 |             for key in flattened:
142 |                 for other_sep in other_separators:
143 |                     assert other_sep not in key or other_sep in str(nested)
144 | 
145 | 
146 | class TestJsonFileOperationsProperty:
147 |     """Property-based tests for JSON file operations."""
148 | 
149 |     # JSON互換のオブジェクトを生成
150 |     json_object = st.dictionaries(
151 |         st.text(min_size=1),
152 |         st.recursive(
153 |             st.none()
154 |             | st.booleans()
155 |             | st.integers()
156 |             | st.floats(allow_nan=False)
157 |             | st.text(),
158 |             lambda children: st.lists(children, max_size=3)
159 |             | st.dictionaries(st.text(), children, max_size=3),
160 |             max_leaves=10,
161 |         ),
162 |         min_size=1,
163 |         max_size=10,
164 |     )
165 | 
166 |     @given(data=json_object)
167 |     def test_プロパティ_保存と読み込みで同じデータが復元される(
168 |         self,
169 |         data: dict,
170 |     ) -> None:
171 |         """JSONファイルへの保存と読み込みでデータが保持されることを検証。"""
172 |         with tempfile.TemporaryDirectory() as temp_dir:
173 |             json_file = Path(temp_dir) / "test_property.json"
174 | 
175 |             save_json_file(data, json_file)
176 |             loaded_data = load_json_file(json_file)
177 | 
178 |             assert loaded_data == data
179 | 
180 |     @given(
181 |         data=json_object,
182 |         indent=st.integers(min_value=0, max_value=8),
183 |     )
184 |     def test_プロパティ_インデントレベルが機能する(
185 |         self,
186 |         data: dict,
187 |         indent: int,
188 |     ) -> None:
189 |         """様々なインデントレベルでも正しく保存・読み込みできることを検証。"""
190 |         with tempfile.TemporaryDirectory() as temp_dir:
191 |             json_file = Path(temp_dir) / "test_indent.json"
192 | 
193 |             save_json_file(data, json_file, indent=indent)
194 |             loaded_data = load_json_file(json_file)
195 | 
196 |             assert loaded_data == data
197 | 
198 |             # インデントが適用されているか確認
199 |             content = json_file.read_text()
200 |             if indent > 0 and len(data) > 0:
201 |                 # ネストがある場合、インデントされた行が存在するはず
202 |                 lines = content.split("\n")
203 |                 if len(lines) > 2:  # 複数行の場合
204 |                     indented_lines = [
205 |                         line for line in lines if line.startswith(" " * indent)
206 |                     ]
207 |                     assert len(indented_lines) > 0
208 | 
209 | 
210 | class TestTypeConversionsProperty:
211 |     """Property-based tests for type conversions and edge cases."""
212 | 
213 |     @given(
214 |         size=st.integers(min_value=0, max_value=1000),
215 |         chunk_size=st.integers(min_value=1, max_value=100),
216 |     )
217 |     def test_プロパティ_様々なリストサイズで正しく動作(
218 |         self,
219 |         size: int,
220 |         chunk_size: int,
221 |     ) -> None:
222 |         """様々なサイズのリストで chunk_list が正しく動作することを検証。"""
223 |         items = list(range(size))
224 |         chunks = chunk_list(items, chunk_size)
225 | 
226 |         # 結果の検証
227 |         if size == 0:
228 |             assert chunks == []
229 |         else:
230 |             assert len(chunks) == (size + chunk_size - 1) // chunk_size
231 | 
232 |             # 全要素が含まれているか
233 |             flattened = [item for chunk in chunks for item in chunk]
234 |             assert flattened == items
235 | 


--------------------------------------------------------------------------------
/Makefile:
--------------------------------------------------------------------------------
  1 | .PHONY: help test test-cov test-unit test-property test-integration format lint typecheck security audit check check-all benchmark profile setup pr issue pr-list issue-list label-list clean
  2 | 
  3 | # デフォルトターゲット
  4 | help:
  5 | 	@echo "Usage: make [target]"
  6 | 	@echo ""
  7 | 	@echo "Available targets:"
  8 | 	@echo "  setup        - セットアップ（依存関係インストール、pre-commit設定）"
  9 | 	@echo "  sync         - 全依存関係を同期"
 10 | 	@echo "  test         - 全テスト実行（単体・プロパティ・統合）"
 11 | 	@echo "  test-cov     - カバレッジ付きテスト実行"
 12 | 	@echo "  test-unit    - 単体テストのみ実行"
 13 | 	@echo "  test-property - プロパティベーステストのみ実行"
 14 | 	@echo "  test-integration - 統合テストのみ実行"
 15 | 	@echo "  format       - コードフォーマット（ruff format）"
 16 | 	@echo "  lint         - リントチェック（ruff check --fix）"
 17 | 	@echo "  typecheck    - 型チェック（pyright）"
 18 | 	@echo "  security     - セキュリティチェック（bandit）"
 19 | 	@echo "  audit        - 依存関係の脆弱性チェック（pip-audit）"
 20 | 	@echo "  benchmark    - パフォーマンスベンチマーク実行"
 21 | 	@echo "  check        - format, lint, typecheck, testを順番に実行"
 22 | 	@echo "  check-all    - pre-commitで全ファイルをチェック"
 23 | 	@echo "  pr           - PR作成 (TITLE=\"タイトル\" BODY=\"本文またはファイルパス\" [LABEL=\"ラベル\"])"
 24 | 	@echo "  pr-list      - 開いているPRの一覧表示"
 25 | 	@echo "  issue        - イシュー作成 (TITLE=\"タイトル\" BODY=\"本文またはファイルパス\" [LABEL=\"ラベル\"])"
 26 | 	@echo "  issue-list   - 開いているイシューの一覧表示"
 27 | 	@echo "  label-list   - 利用可能なラベルの一覧表示"
 28 | 	@echo "  clean        - キャッシュファイルの削除"
 29 | 
 30 | # セットアップ
 31 | setup:
 32 | 	chmod +x scripts/setup.sh && ./scripts/setup.sh
 33 | 
 34 | sync:
 35 | 	uv sync --all-extras
 36 | 
 37 | # テスト関連
 38 | test:
 39 | 	uv run pytest
 40 | 
 41 | test-cov:
 42 | 	uv run pytest --cov=src --cov-report=html --cov-report=term
 43 | 
 44 | test-unit:
 45 | 	uv run pytest tests/unit/ -v
 46 | 
 47 | test-property:
 48 | 	uv run pytest tests/property/ -v
 49 | 
 50 | test-integration:
 51 | 	uv run pytest tests/integration/ -v
 52 | 
 53 | # コード品質チェック
 54 | format:
 55 | 	uv run ruff format . --config=pyproject.toml
 56 | 
 57 | lint:
 58 | 	uv run ruff check . --fix --config=pyproject.toml
 59 | 
 60 | typecheck:
 61 | 	uv run pyright
 62 | 
 63 | security:
 64 | 	uv run bandit -r src/
 65 | 
 66 | audit:
 67 | 	uv run pip-audit
 68 | 
 69 | # パフォーマンス測定
 70 | benchmark:
 71 | 	@echo "Running performance benchmarks..."
 72 | 	@if [ -f benchmark_suite.py ]; then \
 73 | 		uv run pytest benchmark_suite.py --benchmark-only --benchmark-autosave; \
 74 | 	else \
 75 | 		echo "Creating benchmark suite..."; \
 76 | 		echo 'import pytest\nfrom project_name.utils.helpers import chunk_list\n\ndef test_chunk_list_benchmark(benchmark):\n    data = list(range(1000))\n    result = benchmark(chunk_list, data, 10)\n    assert len(result) == 100' > benchmark_suite.py; \
 77 | 		uv add --dev pytest-benchmark; \
 78 | 		uv run pytest benchmark_suite.py --benchmark-only --benchmark-autosave; \
 79 | 	fi
 80 | 
 81 | # 統合チェック
 82 | check: format lint typecheck test
 83 | 
 84 | check-all:
 85 | 	uv run pre-commit run --all-files
 86 | 
 87 | # GitHub操作
 88 | pr:
 89 | 	@if [ -z "$(TITLE)" ]; then \
 90 | 		echo "Error: TITLE is required. Usage: make pr TITLE=\"タイトル\" BODY=\"本文\" [LABEL=\"ラベル\"]"; \
 91 | 		exit 1; \
 92 | 	fi
 93 | 	@if [ -z "$(BODY)" ]; then \
 94 | 		echo "Error: BODY is required. Usage: make pr TITLE=\"タイトル\" BODY=\"本文\" [LABEL=\"ラベル\"]"; \
 95 | 		exit 1; \
 96 | 	fi
 97 | 	@# 現在のブランチを確認
 98 | 	@CURRENT_BRANCH=$$(git rev-parse --abbrev-ref HEAD); \
 99 | 	if [ "$$CURRENT_BRANCH" = "main" ] || [ "$$CURRENT_BRANCH" = "master" ]; then \
100 | 		echo "Error: Cannot create PR from main/master branch."; \
101 | 		echo "Please create a new branch first:"; \
102 | 		echo "  git checkout -b feature/your-feature-name"; \
103 | 		exit 1; \
104 | 	fi
105 | 	@# 変更がステージングされているか確認
106 | 	@if ! git diff --cached --quiet; then \
107 | 		echo "Warning: You have staged changes. Consider committing them first."; \
108 | 	fi
109 | 	@# 変更がコミットされていない場合の警告
110 | 	@if ! git diff --quiet; then \
111 | 		echo "Warning: You have uncommitted changes."; \
112 | 	fi
113 | 	@# ラベルが指定されていて、存在しない場合は作成
114 | 	@if [ -n "$(LABEL)" ]; then \
115 | 		if ! gh label list --limit 1000 | grep -q "^$(LABEL)"; then \
116 | 			echo "Creating label: $(LABEL)"; \
117 | 			case "$(LABEL)" in \
118 | 				bug) gh label create "$(LABEL)" --description "バグ修正" --color "d73a4a" ;; \
119 | 				enhancement) gh label create "$(LABEL)" --description "新機能" --color "a2eeef" ;; \
120 | 				documentation) gh label create "$(LABEL)" --description "ドキュメント更新" --color "0075ca" ;; \
121 | 				test) gh label create "$(LABEL)" --description "テスト関連" --color "d4c5f9" ;; \
122 | 				refactor) gh label create "$(LABEL)" --description "リファクタリング" --color "1d76db" ;; \
123 | 				*) gh label create "$(LABEL)" --description "カスタムラベル" --color "e4e669" ;; \
124 | 			esac; \
125 | 		fi; \
126 | 	fi
127 | 	@# ファイルを使って本文を渡すか、簡単な本文の場合は直接渡す
128 | 	@if [ -f "$(BODY)" ]; then \
129 | 		echo "Using file content for PR body: $(BODY)"; \
130 | 		if [ -n "$(LABEL)" ]; then \
131 | 			gh pr create --title "$(TITLE)" --body-file "$(BODY)" --label "$(LABEL)"; \
132 | 		else \
133 | 			gh pr create --title "$(TITLE)" --body-file "$(BODY)"; \
134 | 		fi; \
135 | 	else \
136 | 		if [ -n "$(LABEL)" ]; then \
137 | 			gh pr create --title "$(TITLE)" --body "$(BODY)" --label "$(LABEL)"; \
138 | 		else \
139 | 			gh pr create --title "$(TITLE)" --body "$(BODY)"; \
140 | 		fi; \
141 | 	fi
142 | 
143 | issue:
144 | 	@if [ -z "$(TITLE)" ]; then \
145 | 		echo "Error: TITLE is required. Usage: make issue TITLE=\"タイトル\" BODY=\"本文\" [LABEL=\"ラベル\"]"; \
146 | 		exit 1; \
147 | 	fi
148 | 	@if [ -z "$(BODY)" ]; then \
149 | 		echo "Error: BODY is required. Usage: make issue TITLE=\"タイトル\" BODY=\"本文\" [LABEL=\"ラベル\"]"; \
150 | 		exit 1; \
151 | 	fi
152 | 	@# GitHub CLI が利用可能か確認
153 | 	@if ! command -v gh >/dev/null 2>&1; then \
154 | 		echo "Error: GitHub CLI (gh) is not installed."; \
155 | 		echo "Please install it first: https://cli.github.com/"; \
156 | 		exit 1; \
157 | 	fi
158 | 	@# 認証状態を確認
159 | 	@if ! gh auth status >/dev/null 2>&1; then \
160 | 		echo "Error: Not authenticated with GitHub."; \
161 | 		echo "Please run: gh auth login"; \
162 | 		exit 1; \
163 | 	fi
164 | 	@# ラベルが指定されていて、存在しない場合は作成
165 | 	@if [ -n "$(LABEL)" ]; then \
166 | 		if ! gh label list --limit 1000 | grep -q "^$(LABEL)"; then \
167 | 			echo "Creating label: $(LABEL)"; \
168 | 			case "$(LABEL)" in \
169 | 				bug) gh label create "$(LABEL)" --description "バグ修正" --color "d73a4a" ;; \
170 | 				enhancement) gh label create "$(LABEL)" --description "新機能" --color "a2eeef" ;; \
171 | 				documentation) gh label create "$(LABEL)" --description "ドキュメント更新" --color "0075ca" ;; \
172 | 				test) gh label create "$(LABEL)" --description "テスト関連" --color "d4c5f9" ;; \
173 | 				refactor) gh label create "$(LABEL)" --description "リファクタリング" --color "1d76db" ;; \
174 | 				*) gh label create "$(LABEL)" --description "カスタムラベル" --color "e4e669" ;; \
175 | 			esac; \
176 | 		fi; \
177 | 	fi
178 | 	@# ファイルを使って本文を渡すか、簡単な本文の場合は直接渡す
179 | 	@if [ -f "$(BODY)" ]; then \
180 | 		echo "Using file content for issue body: $(BODY)"; \
181 | 		if [ -n "$(LABEL)" ]; then \
182 | 			gh issue create --title "$(TITLE)" --body-file "$(BODY)" --label "$(LABEL)"; \
183 | 		else \
184 | 			gh issue create --title "$(TITLE)" --body-file "$(BODY)"; \
185 | 		fi; \
186 | 	else \
187 | 		if [ -n "$(LABEL)" ]; then \
188 | 			gh issue create --title "$(TITLE)" --body "$(BODY)" --label "$(LABEL)"; \
189 | 		else \
190 | 			gh issue create --title "$(TITLE)" --body "$(BODY)"; \
191 | 		fi; \
192 | 	fi
193 | 
194 | # PRとイシューの一覧表示
195 | pr-list:
196 | 	@echo "=== Open Pull Requests ==="
197 | 	@gh pr list --state open || echo "No open pull requests found."
198 | 
199 | issue-list:
200 | 	@echo "=== Open Issues ==="
201 | 	@gh issue list --state open || echo "No open issues found."
202 | 
203 | label-list:
204 | 	@echo "=== Available Labels ==="
205 | 	@gh label list || echo "No labels found."
206 | 
207 | # クリーンアップ
208 | clean:
209 | 	find . -type d -name "__pycache__" -exec rm -rf {} +
210 | 	find . -type f -name "*.pyc" -delete
211 | 	find . -type d -name ".pytest_cache" -exec rm -rf {} +
212 | 	find . -type d -name ".mypy_cache" -exec rm -rf {} +
213 | 	find . -type d -name ".ruff_cache" -exec rm -rf {} +
214 | 	find . -type d -name "htmlcov" -exec rm -rf {} +
215 | 	find . -type f -name ".coverage" -delete
216 | 


--------------------------------------------------------------------------------
/CLAUDE.md:
--------------------------------------------------------------------------------
  1 | ---
  2 | title: CLAUDE.md
  3 | created_at: 2025-06-14
  4 | updated_at: 2025-07-14
  5 | # このプロパティは、Claude Codeが関連するドキュメントの更新を検知するために必要です。消去しないでください。
  6 | ---
  7 | 
  8 | # Python開発テンプレート for Claude Code
  9 | 
 10 | 適度な型チェック、自動化されたコード品質管理、CI/CDを備えたPython 3.12+プロジェクトテンプレート。
 11 | 
 12 | ## 技術スタック
 13 | 
 14 | **Python 3.12+** | uv | Ruff | pyright | pytest + Hypothesis | pre-commit | GitHub Actions
 15 | 
 16 | ## プロジェクト構造(デフォルト。必要に応じて更新してください)
 17 | 
 18 | 
 19 | ```
 20 | project-root/
 21 | ├── .github/
 22 | │   ├── workflows/
 23 | │   │   ├── ci.yml
 24 | │   │   └── benchmark.yml
 25 | │   ├── dependabot.yml
 26 | │   ├── ISSUE_TEMPLATE/
 27 | │   └── PULL_REQUEST_TEMPLATE.md
 28 | ├── template/
 29 | │   ├── src/
 30 | │   │   └── template_package/    # モデルパッケージの完全な実装例
 31 | │   │       ├── __init__.py      # パッケージエクスポートの例
 32 | │   │       ├── py.typed         # 型情報マーカーの例
 33 | │   │       ├── types.py         # 型定義のベストプラクティス
 34 | │   │       ├── core/
 35 | │   │       │   └── example.py   # クラス・関数実装の模範例
 36 | │   │       └── utils/
 37 | │   │           ├── helpers.py   # ユーティリティ関数の実装例
 38 | │   │           ├── logging_config.py # ロギング設定の実装例
 39 | │   │           └── profiling.py # パフォーマンス測定の実装例
 40 | │   └── tests/                   # テストコードの完全な実装例
 41 | │       ├── unit/                # 単体テスト
 42 | │       ├── property/            # プロパティベーステスト
 43 | │       ├── integration/         # 結合テスト
 44 | │       └── conftest.py          # pytestフィクスチャ
 45 | ├── src/                         # 実際の開発用ディレクトリ
 46 | │       └── project_name/
 47 | │           └── （プロジェクト固有のパッケージを配置）
 48 | ├── tests/                       # 実際のテスト用ディレクトリ
 49 | │   ├── unit/
 50 | │   ├── property/
 51 | │   ├── integration/
 52 | │   └── conftest.py
 53 | ├── docs/                        # ドキュメント
 54 | ├── scripts/
 55 | ├── pyproject.toml
 56 | ├── .gitignore
 57 | ├── .pre-commit-config.yaml
 58 | ├── README.md
 59 | └── CLAUDE.md
 60 | ```
 61 | 
 62 | ## 実装時の必須要件
 63 | 
 64 | ### 0. 開発環境
 65 | - **パッケージ管理**: uvで環境を統一管理。Pythonコマンドは必ず `uv run` を前置
 66 | - **依存関係追加**: `uv add` (通常) / `uv add --dev` (開発用)
 67 | - **GitHub操作**: `make pr`/`make issue` または `gh`コマンド
 68 | - **品質保証**: pre-commitフック設定済み。`make check-all` で包括的チェック
 69 | - **開発支援**: Makefileに開発効率化コマンド集約。`make help` で一覧表示
 70 | 
 71 | ### 1-5. 実装フロー
 72 | 1. **品質**: format→lint→typecheck→test
 73 | 2. **テスト**: 新機能::TDD必須
 74 | 3. **ロギング**: 全コード::ログ必須
 75 | 4. **性能**: 重い処理→プロファイル
 76 | 5. **段階的**: Protocol»テスト»実装»最適化
 77 | 
 78 | ### 6. エビデンスベース開発
 79 | 
 80 | **禁止語**: best, optimal, faster, always, never, perfect
 81 | **推奨語**: measured, documented, approximately, typically
 82 | 
 83 | **証拠要件**:
 84 | - **性能**: "measured Xms" | "reduces X%"
 85 | - **品質**: "coverage X%" | "complexity Y"
 86 | - **セキュリティ**: "scan detected X"
 87 | - **信頼性**: "uptime X%" | "error rate Y%"
 88 | 
 89 | ### 7. 効率化テクニック
 90 | 
 91 | #### コミュニケーション記法
 92 | ```yaml
 93 | →: "処理フロー"      # analyze→fix→test
 94 | |: "選択/区切り"     # option1|option2
 95 | &: "並列/結合"       # task1 & task2
 96 | ::: "定義"           # variable :: value
 97 | »: "シーケンス"      # step1 » step2
 98 | @: "参照/場所"       # @file:line
 99 | ```
100 | 
101 | #### 実行パターン
102 | - **並列**: 依存なし&競合なし&順序不問 → 複数ファイル読込|独立テスト|並列ビルド
103 | - **バッチ**: 同種操作&共通リソース → 一括フォーマット|インポート修正|バッチテスト
104 | - **逐次**: 依存あり|状態変更|トランザクション → DBマイグレ|段階的リファクタ|依存インストール
105 | 
106 | #### エラーリカバリー
107 | - **リトライ**: max3回 & 指数バックオフ
108 | - **フォールバック**: 高速→確実
109 | - **状態復元**: チェックポイント»ロールバック|正常状態»再開|失敗のみ»再実行
110 | 
111 | #### 建設的フィードバックの提供
112 | 
113 | **フィードバックのトリガー**:
114 | - 非効率なアプローチを検出
115 | - セキュリティリスクを発見
116 | - 過剰設計を認識
117 | - 不適切な実践を確認
118 | 
119 | **アプローチ**:
120 | - 直接的な表現 > 婉曲的な表現
121 | - エビデンスベースの代替案 > 単なる批判
122 | - 例: "より効率的な方法: X" | "セキュリティリスク: SQLインジェクション"
123 | 
124 | ## template/ディレクトリの活用
125 | 
126 | 実装前に必ず参照:
127 | - **クラス/関数**: @template/src/template_package/core/example.py (型ヒント|docstring|エラー処理)
128 | - **型定義**: @template/src/template_package/types.py
129 | - **ユーティリティ**: @template/src/template_package/utils/helpers.py
130 | - **テスト**: @template/tests/{unit|property|integration}/
131 | - **フィクスチャ**: @template/tests/conftest.py
132 | - **ロギング**: @template/src/template_package/utils/logging_config.py
133 | 実装時: template/内の類似例確認»パターン踏襲»プロジェクト調整
134 | 注: template/は変更&削除禁止
135 | 
136 | ## よく使うコマンド
137 | 
138 | ```bash
139 | # 初期セットアップ
140 | make setup              # 依存関係インストール + pre-commitフック設定
141 | 
142 | # 基本
143 | make help               # コマンド一覧
144 | make check-all          # 全チェック実行
145 | make clean              # キャッシュ削除
146 | 
147 | # 品質チェック
148 | make format             # フォーマット
149 | make lint               # リント
150 | make typecheck          # 型チェック
151 | make test               # テスト実行
152 | make test-cov           # カバレッジ付きテスト
153 | 
154 | # GitHub操作
155 | make pr TITLE="x" BODY="y" [LABEL="z"]     # PR作成
156 | make issue TITLE="x" BODY="y"              # Issue作成
157 | # 注: BODYにはファイルパス指定可能 (例: BODY="/tmp/pr_body.md")
158 | # 注: 存在しないラベルは自動作成される
159 | 
160 | # 依存関係
161 | uv add package_name               # 通常パッケージ
162 | uv add --dev package_name         # 開発用パッケージ
163 | make sync                         # 全依存関係を同期
164 | uv lock --upgrade                 # 依存関係を更新
165 | ```
166 | 
167 | ## Git規則
168 | 
169 | **ブランチ**: feature/ | fix/ | refactor/ | docs/ | test/
170 | **ラベル**: enhancement | bug | refactor | documentation | test
171 | 
172 | ## コーディング規約
173 | 
174 | ### ディレクトリ構成
175 | 
176 | パッケージとテストは `template/` 内の構造を踏襲、コアロジックは必ず `src/project_name` 内に配置
177 | 
178 | ```
179 | src/
180 | ├── project_name/
181 | │   ├── core/
182 | │   ├── utils/
183 | │   ├── __init__.py
184 | │   └── ...
185 | ├── tests/
186 | │   ├── unit/
187 | │   ├── property/
188 | │   ├── integration/
189 | │   └── conftest.py
190 | ├── docs/
191 | ...
192 | ```
193 | 
194 | ### Python コーディングスタイル
195 | - 型ヒント: Python 3.12+スタイル必須（pyright + PEP 695）
196 | - Docstring: NumPy形式
197 | - 命名: クラス(PascalCase)、関数(snake_case)、定数(UPPER_SNAKE)、プライベート(_prefix)
198 | - ベストプラクティス: @template/src/template_package/types.py
199 | 
200 | ### エラーメッセージ
201 | 
202 | 1. **具体的**: "Invalid input" → "Expected positive integer, got {count}"
203 | 2. **コンテキスト付き**: "Failed to process {source_file}: {e}"
204 | 3. **解決策を提示**: "Not found. Create by: python -m {__package__}.init"
205 | 
206 | ### アンカーコメント
207 | ```python
208 | # AIDEV-NOTE: 説明
209 | # AIDEV-TODO: 課題
210 | # AIDEV-QUESTION: 疑問
211 | ```
212 | 
213 | ## テスト戦略（TDD）
214 | 
215 | t-wada流のテスト駆動開発（TDD）を徹底
216 | 
217 | ### サイクル
218 | 🔴 Red » 🟢 Green » 🔵 Refactor
219 | 
220 | ### 手順
221 | 1. TODO作成
222 | 2. 失敗テスト
223 | 3. 最小実装（仮実装OK）
224 | 4. リファクタ
225 | 
226 | ### 原則
227 | - 小さなステップで進める
228 | - 三角測量で一般化
229 | - 不安な部分から着手
230 | - テストリストを常に更新
231 | 
232 | #### 三角測量の例
233 | ```python
234 | # 1. 仮実装: return 5
235 | assert add(2, 3) == 5
236 | 
237 | # 2. 一般化: return a + b
238 | assert add(10, 20) == 30
239 | 
240 | # 3. エッジケース確認
241 | assert add(-1, -2) == -3
242 | ```
243 | 
244 | #### 注意点
245 | - 1test::1behavior
246 | - Red»Greenでコミット
247 | - 日本語テスト名推奨
248 | - リファクタ: 重複|可読性|SOLID違反時
249 | 
250 | ### テスト種別
251 | 1. **単体**: 基本動作 `template/tests/unit/`
252 | 2. **プロパティ**: Hypothesis自動生成 `template/tests/property/`
253 | 3. **統合**: 連携テスト `template/tests/integration/`
254 | 
255 | ### テスト命名
256 | `test_[正常系|異常系|エッジケース]_条件で結果()`
257 | 
258 | ## ロギング
259 | 
260 | ### 必須要件
261 | 1. モジュール冒頭::ロガー定義
262 | 2. 関数開始&終了::ログ出力
263 | 3. エラー時::exc_info=True
264 | 4. レベル: DEBUG|INFO|WARNING|ERROR
265 | 
266 | ベストプラクティス: @template/src/template_package/utils/logging_config.py & @template/src/template_package/core/example.py
267 | 
268 | ### 設定
269 | ```python
270 | setup_logging(level="INFO")
271 | # または export LOG_LEVEL=INFO
272 | ```
273 | 
274 | ### テスト時の設定
275 | ```bash
276 | # 環境変数でテスト時のログレベル制御
277 | export TEST_LOG_LEVEL=INFO  # デフォルトはDEBUG
278 | ```
279 | 
280 | ```python
281 | # 個別テストでログレベル変更
282 | def test_カスタムログレベル(set_test_log_level):
283 |     set_test_log_level("WARNING")
284 |     # テスト実行
285 | ```
286 | 
287 | ## パフォーマンス測定
288 | 
289 | ```python
290 | from template_package.utils.profiling import profile, timeit, Timer
291 | 
292 | @profile  # 詳細プロファイル
293 | @timeit   # 実行時間計測
294 | def func(): ...
295 | 
296 | with Timer("operation"):  # ブロック計測
297 |     ...
298 | ```
299 | 
300 | ベストプラクティス: @template/src/template_package/utils/profiling.py
301 | 
302 | ## 更新トリガー
303 | 
304 | - 仕様/依存関係/構造/規約の変更時
305 | - 同一質問2回以上 → FAQ追加
306 | - エラーパターン2回以上 → トラブルシューティング追加
307 | 
308 | ## トラブルシューティング/FAQ
309 | 
310 | 適宜更新
311 | 
312 | ## カスタムガイド
313 | 
314 | `docs/`に追加可能。追加時はCLAUDE.mdに概要記載必須。
315 | 


--------------------------------------------------------------------------------
/template/src/template_package/utils/helpers.py:
--------------------------------------------------------------------------------
  1 | """Utility helper functions."""
  2 | 
  3 | import json
  4 | from collections.abc import Mapping
  5 | from pathlib import Path
  6 | from typing import Any, TypeVar
  7 | 
  8 | from ..types import JSONObject, JSONValue
  9 | 
 10 | T = TypeVar("T")
 11 | 
 12 | 
 13 | # ロガーを遅延初期化で循環インポートを回避
 14 | def _get_logger() -> Any:
 15 |     try:
 16 |         from ..utils.logging_config import get_logger
 17 | 
 18 |         return get_logger(__name__, module="helpers")
 19 |     except ImportError:
 20 |         import logging
 21 | 
 22 |         return logging.getLogger(__name__)
 23 | 
 24 | 
 25 | logger: Any = _get_logger()
 26 | 
 27 | 
 28 | def load_json_file(filepath: str | Path) -> JSONObject:
 29 |     """Load JSON data from a file.
 30 | 
 31 |     Parameters
 32 |     ----------
 33 |     filepath : str | Path
 34 |         Path to JSON file
 35 | 
 36 |     Returns
 37 |     -------
 38 |     JSONObject
 39 |         Loaded JSON data as a dictionary
 40 | 
 41 |     Raises
 42 |     ------
 43 |     FileNotFoundError
 44 |         If file doesn't exist
 45 |     ValueError
 46 |         If file contains invalid JSON
 47 |     """
 48 |     path = Path(filepath)
 49 |     logger.debug(
 50 |         "Loading JSON file",
 51 |         file_path=str(path),
 52 |         file_exists=path.exists(),
 53 |         file_size=path.stat().st_size if path.exists() else None,
 54 |     )
 55 | 
 56 |     if not path.exists():
 57 |         logger.error(
 58 |             "File not found",
 59 |             file_path=str(path),
 60 |             absolute_path=str(path.absolute()),
 61 |         )
 62 |         raise FileNotFoundError(f"File not found: {path}")
 63 | 
 64 |     try:
 65 |         logger.debug("Opening file", file_path=str(path))
 66 |         with path.open("r", encoding="utf-8") as f:
 67 |             result = json.load(f)
 68 |             logger.debug(
 69 |                 "Successfully loaded JSON data",
 70 |                 file_path=str(path),
 71 |                 data_type=type(result).__name__,
 72 |             )
 73 | 
 74 |             # json.load returns Any, but we expect dict[str, Any]
 75 |             if not isinstance(result, dict):
 76 |                 type_name = type(result).__name__
 77 |                 logger.error(
 78 |                     "Invalid JSON structure",
 79 |                     file_path=str(path),
 80 |                     expected_type="object",
 81 |                     actual_type=type_name,
 82 |                 )
 83 |                 raise ValueError(f"Expected JSON object in {path}, got {type_name}")
 84 | 
 85 |             logger.debug(
 86 |                 "JSON object loaded",
 87 |                 file_path=str(path),
 88 |                 key_count=len(result),
 89 |                 keys=list(result.keys())[:5],  # 最初の5キーのみ
 90 |             )
 91 |             return result
 92 |     except json.JSONDecodeError as e:
 93 |         logger.error(
 94 |             "Failed to parse JSON",
 95 |             file_path=str(path),
 96 |             error_type=type(e).__name__,
 97 |             error_message=str(e),
 98 |             line_number=e.lineno if hasattr(e, "lineno") else None,
 99 |             column_number=e.colno if hasattr(e, "colno") else None,
100 |         )
101 |         raise ValueError(f"Invalid JSON in {path}: {e}") from e
102 | 
103 | 
104 | def save_json_file(
105 |     data: JSONObject,
106 |     filepath: str | Path,
107 |     *,
108 |     indent: int = 2,
109 |     ensure_ascii: bool = False,
110 | ) -> None:
111 |     """Save data to a JSON file.
112 | 
113 |     Parameters
114 |     ----------
115 |     data : JSONObject
116 |         JSON-compatible dictionary to save
117 |     filepath : str | Path
118 |         Path to save to
119 |     indent : int
120 |         JSON indentation level
121 |     ensure_ascii : bool
122 |         Whether to escape non-ASCII characters
123 |     """
124 |     path = Path(filepath)
125 |     logger.debug(
126 |         "Saving JSON data",
127 |         file_path=str(path),
128 |         indent=indent,
129 |         ensure_ascii=ensure_ascii,
130 |         key_count=len(data),
131 |     )
132 | 
133 |     # ディレクトリが存在しない場合は作成
134 |     if not path.parent.exists():
135 |         logger.debug(
136 |             "Creating directory",
137 |             directory_path=str(path.parent),
138 |             directory_exists=path.parent.exists(),
139 |         )
140 |     path.parent.mkdir(parents=True, exist_ok=True)
141 | 
142 |     logger.debug(
143 |         "Writing JSON data",
144 |         file_path=str(path),
145 |         key_count=len(data),
146 |         data_size_estimate=len(str(data)),
147 |     )
148 |     with path.open("w", encoding="utf-8") as f:
149 |         json.dump(data, f, indent=indent, ensure_ascii=ensure_ascii)
150 |     logger.info(
151 |         "JSON file saved successfully",
152 |         file_path=str(path),
153 |         file_size=path.stat().st_size if path.exists() else None,
154 |         key_count=len(data),
155 |     )
156 | 
157 | 
158 | def chunk_list(items: list[T], chunk_size: int) -> list[list[T]]:
159 |     """Split a list into chunks of specified size.
160 | 
161 |     Parameters
162 |     ----------
163 |     items : list[T]
164 |         Items to chunk
165 |     chunk_size : int
166 |         Size of each chunk
167 | 
168 |     Returns
169 |     -------
170 |     list[list[T]]
171 |         List of chunks
172 | 
173 |     Raises
174 |     ------
175 |     ValueError
176 |         If chunk_size is not positive
177 | 
178 |     Examples
179 |     --------
180 |     >>> chunk_list([1, 2, 3, 4, 5], 2)
181 |     [[1, 2], [3, 4], [5]]
182 |     """
183 |     if chunk_size <= 0:
184 |         logger.error(
185 |             "Invalid chunk_size",
186 |             chunk_size=chunk_size,
187 |             error="chunk_size must be positive",
188 |         )
189 |         raise ValueError(f"chunk_size must be positive, got {chunk_size}")
190 | 
191 |     logger.debug(
192 |         "Chunking list",
193 |         item_count=len(items),
194 |         chunk_size=chunk_size,
195 |         expected_chunks=(len(items) + chunk_size - 1) // chunk_size if items else 0,
196 |     )
197 | 
198 |     chunks = [items[i : i + chunk_size] for i in range(0, len(items), chunk_size)]
199 |     logger.debug(
200 |         "Chunking completed",
201 |         input_count=len(items),
202 |         chunk_count=len(chunks),
203 |         chunk_size=chunk_size,
204 |         last_chunk_size=len(chunks[-1]) if chunks else 0,
205 |     )
206 | 
207 |     return chunks
208 | 
209 | 
210 | def flatten_dict(
211 |     nested_dict: Mapping[str, JSONValue],
212 |     *,
213 |     separator: str = ".",
214 |     prefix: str = "",
215 | ) -> Mapping[str, JSONValue]:
216 |     """Flatten a nested dictionary.
217 | 
218 |     Parameters
219 |     ----------
220 |     nested_dict : dict[str, JSONValue]
221 |         Dictionary with JSON-compatible values to flatten
222 |     separator : str
223 |         Separator for keys
224 |     prefix : str
225 |         Prefix for all keys
226 | 
227 |     Returns
228 |     -------
229 |     Mapping[str, JSONValue]
230 |         Flattened dictionary with dot-notation keys
231 | 
232 |     Examples
233 |     --------
234 |     >>> flatten_dict({"a": {"b": 1, "c": 2}})
235 |     {"a.b": 1, "a.c": 2}
236 |     """
237 |     logger.debug(
238 |         "Flattening dictionary",
239 |         input_keys=len(nested_dict),
240 |         separator=separator,
241 |         has_prefix=bool(prefix),
242 |         prefix=prefix if prefix else None,
243 |     )
244 | 
245 |     items: list[tuple[str, JSONValue]] = []
246 | 
247 |     for key, value in nested_dict.items():
248 |         new_key = f"{prefix}{separator}{key}" if prefix else key
249 |         logger.debug(
250 |             "Processing dictionary key",
251 |             original_key=key,
252 |             new_key=new_key,
253 |             value_type=type(value).__name__,
254 |             is_nested=isinstance(value, dict),
255 |         )
256 | 
257 |         if isinstance(value, dict):
258 |             logger.debug(
259 |                 "Found nested dictionary",
260 |                 key=key,
261 |                 nested_key_count=len(value),
262 |                 nesting_level=prefix.count(separator) + 1 if prefix else 1,
263 |             )
264 |             items.extend(
265 |                 flatten_dict(value, separator=separator, prefix=new_key).items()
266 |             )
267 |         else:
268 |             items.append((new_key, value))
269 | 
270 |     result = dict(items)
271 |     logger.debug(
272 |         "Dictionary flattening completed",
273 |         input_key_count=len(nested_dict),
274 |         output_key_count=len(result),
275 |         keys_expanded=len(result) - len(nested_dict),
276 |         flattening_ratio=round(len(result) / len(nested_dict), 2) if nested_dict else 0,
277 |     )
278 | 
279 |     return result
280 | 


--------------------------------------------------------------------------------
/template/src/template_package/core/example.py:
--------------------------------------------------------------------------------
  1 | """Example module demonstrating best practices."""
  2 | 
  3 | from dataclasses import dataclass
  4 | from typing import Any, Protocol
  5 | 
  6 | from ..types import ItemDict
  7 | 
  8 | 
  9 | # ロガーを遅延初期化で循環インポートを回避
 10 | def _get_logger() -> Any:
 11 |     try:
 12 |         from ..utils.logging_config import get_logger
 13 | 
 14 |         return get_logger(__name__, module="example")
 15 |     except ImportError:
 16 |         import logging
 17 | 
 18 |         return logging.getLogger(__name__)
 19 | 
 20 | 
 21 | logger: Any = _get_logger()
 22 | 
 23 | 
 24 | class DataProcessor(Protocol):
 25 |     """Protocol for data processors."""
 26 | 
 27 |     def process(self, data: list[ItemDict]) -> list[ItemDict]:
 28 |         """Process a list of data items."""
 29 |         ...
 30 | 
 31 | 
 32 | @dataclass
 33 | class ExampleConfig:
 34 |     """Configuration for ExampleClass."""
 35 | 
 36 |     name: str
 37 |     max_items: int = 100
 38 |     enable_validation: bool = True
 39 | 
 40 |     def __post_init__(self) -> None:
 41 |         """Validate configuration after initialization."""
 42 |         logger.debug(
 43 |             "Initializing ExampleConfig",
 44 |             name=self.name,
 45 |             max_items=self.max_items,
 46 |         )
 47 |         if self.max_items <= 0:
 48 |             logger.error(
 49 |                 "Invalid max_items value",
 50 |                 max_items=self.max_items,
 51 |                 error="max_items must be positive",
 52 |             )
 53 |             raise ValueError(f"max_items must be positive, got {self.max_items}")
 54 |         logger.debug("ExampleConfig validation completed", status="success")
 55 | 
 56 | 
 57 | class ExampleClass:
 58 |     """Example class demonstrating type hints and documentation.
 59 | 
 60 |     This class shows how to properly structure a Python class with:
 61 |     - Type hints for all methods
 62 |     - Comprehensive docstrings
 63 |     - Proper error handling
 64 | 
 65 |     Attributes
 66 |     ----------
 67 |     config : ExampleConfig
 68 |         Configuration for this instance
 69 |     data : list[dict[str, Any]]
 70 |         Internal data storage
 71 | 
 72 |     Examples
 73 |     --------
 74 |     >>> config = ExampleConfig(name="test", max_items=50)
 75 |     >>> example = ExampleClass(config)
 76 |     >>> example.add_item({"id": 1, "value": "test"})
 77 |     >>> len(example)
 78 |     1
 79 |     """
 80 | 
 81 |     def __init__(self, config: ExampleConfig) -> None:
 82 |         """Initialize ExampleClass with configuration.
 83 | 
 84 |         Parameters
 85 |         ----------
 86 |         config : ExampleConfig
 87 |             Configuration object
 88 |         """
 89 |         logger.debug(
 90 |             "Creating ExampleClass instance",
 91 |             config_name=config.name,
 92 |             max_items=config.max_items,
 93 |             validation_enabled=config.enable_validation,
 94 |         )
 95 |         self.config = config
 96 |         self.data: list[ItemDict] = []
 97 |         logger.info(
 98 |             "ExampleClass initialized",
 99 |             name=config.name,
100 |             max_items=config.max_items,
101 |             instance_id=id(self),
102 |         )
103 | 
104 |     def add_item(self, item: ItemDict) -> None:
105 |         """Add an item to the internal storage.
106 | 
107 |         Parameters
108 |         ----------
109 |         item : dict[str, Any]
110 |             Item to add
111 | 
112 |         Raises
113 |         ------
114 |         ValueError
115 |             If max_items limit is reached or validation fails
116 |         """
117 |         logger.debug(
118 |             "Adding item",
119 |             item_id=item.get("id"),
120 |             item_name=item.get("name"),
121 |             current_count=len(self.data),
122 |         )
123 | 
124 |         if len(self.data) >= self.config.max_items:
125 |             logger.warning(
126 |                 "Cannot add item: max_items limit reached",
127 |                 max_items=self.config.max_items,
128 |                 current_count=len(self.data),
129 |                 item_id=item.get("id"),
130 |             )
131 |             raise ValueError(
132 |                 f"Cannot add item: max_items limit ({self.config.max_items}) reached"
133 |             )
134 | 
135 |         if self.config.enable_validation:
136 |             logger.debug("Validating item", validation_enabled=True)
137 |             self._validate_item(item)
138 | 
139 |         self.data.append(item)
140 |         logger.debug(
141 |             "Item added successfully",
142 |             item_id=item.get("id"),
143 |             total_items=len(self.data),
144 |             capacity_used_percent=round(
145 |                 (len(self.data) / self.config.max_items) * 100, 1
146 |             ),
147 |         )
148 | 
149 |     def _validate_item(self, item: ItemDict) -> None:
150 |         """Validate an item before adding.
151 | 
152 |         Parameters
153 |         ----------
154 |         item : dict[str, Any]
155 |             Item to validate
156 | 
157 |         Raises
158 |         ------
159 |         ValueError
160 |             If item is invalid
161 |         """
162 |         logger.debug(
163 |             "Validating item",
164 |             item_keys=list(item.keys()),
165 |             has_id="id" in item,
166 |             has_name="name" in item,
167 |             has_value="value" in item,
168 |         )
169 | 
170 |         # Validate required fields
171 |         required_fields = {"id", "name", "value"}
172 |         missing_fields = required_fields - set(item.keys())
173 |         if missing_fields:
174 |             logger.error(
175 |                 "Missing required fields",
176 |                 missing_fields=list(missing_fields),
177 |                 provided_fields=list(item.keys()),
178 |                 required_fields=list(required_fields),
179 |             )
180 |             raise ValueError(f"Missing required fields: {missing_fields}")
181 | 
182 |         # Check if all required fields have truthy values (not None or empty)
183 |         invalid_fields = [field for field in required_fields if not item.get(field)]
184 |         if invalid_fields:
185 |             logger.error(
186 |                 "Required fields have empty or None values",
187 |                 item_id=item.get("id"),
188 |                 invalid_fields=invalid_fields,
189 |                 field_values={field: item.get(field) for field in invalid_fields},
190 |             )
191 |             raise ValueError(
192 |                 f"Required fields cannot be None or empty: {invalid_fields}"
193 |             )
194 | 
195 |         logger.debug("Item validation passed", status="valid")
196 | 
197 |     def get_items(
198 |         self,
199 |         *,
200 |         filter_key: str | None = None,
201 |         filter_value: Any | None = None,
202 |     ) -> list[ItemDict]:
203 |         """Get items with optional filtering.
204 | 
205 |         Parameters
206 |         ----------
207 |         filter_key : str | None
208 |             Key to filter by
209 |         filter_value : Any | None
210 |             Value to filter by
211 | 
212 |         Returns
213 |         -------
214 |         list[dict[str, Any]]
215 |             Filtered items
216 |         """
217 |         logger.debug(
218 |             "Getting items",
219 |             filter_key=filter_key,
220 |             filter_value=filter_value,
221 |             total_items=len(self.data),
222 |         )
223 | 
224 |         if filter_key is None or filter_value is None:
225 |             logger.debug(
226 |                 "No filter applied",
227 |                 returning_all=True,
228 |                 item_count=len(self.data),
229 |             )
230 |             return self.data.copy()
231 | 
232 |         filtered = [item for item in self.data if item.get(filter_key) == filter_value]
233 |         logger.debug(
234 |             "Filter applied",
235 |             filter_key=filter_key,
236 |             filter_value=filter_value,
237 |             matched_count=len(filtered),
238 |             total_count=len(self.data),
239 |             match_rate_percent=round(
240 |                 (len(filtered) / len(self.data) * 100) if self.data else 0, 1
241 |             ),
242 |         )
243 |         return filtered
244 | 
245 |     def __len__(self) -> int:
246 |         """Return the number of items."""
247 |         return len(self.data)
248 | 
249 |     def __repr__(self) -> str:
250 |         """Return string representation."""
251 |         return (
252 |             f"ExampleClass(name={self.config.name!r}, "
253 |             f"items={len(self)}/{self.config.max_items})"
254 |         )
255 | 
256 | 
257 | def process_data(
258 |     data: list[ItemDict],
259 |     processor: DataProcessor,
260 |     *,
261 |     validate: bool = True,
262 | ) -> list[ItemDict]:
263 |     """Process data using a processor.
264 | 
265 |     Parameters
266 |     ----------
267 |     data : list[dict[str, Any]]
268 |         Data to process
269 |     processor : DataProcessor
270 |         Processor to use
271 |     validate : bool
272 |         Whether to validate data before processing
273 | 
274 |     Returns
275 |     -------
276 |     list[dict[str, Any]]
277 |         Processed data
278 | 
279 |     Raises
280 |     ------
281 |     ValueError
282 |         If validation fails
283 |     """
284 |     logger.debug(
285 |         "Processing data",
286 |         item_count=len(data),
287 |         validation_enabled=validate,
288 |         processor_type=processor.__class__.__name__,
289 |     )
290 | 
291 |     if validate and not data:
292 |         logger.error(
293 |             "Data validation failed",
294 |             reason="empty data",
295 |             validation_enabled=True,
296 |         )
297 |         raise ValueError("Data cannot be empty")
298 | 
299 |     logger.debug(
300 |         "Calling processor",
301 |         processor_class=processor.__class__.__name__,
302 |         input_count=len(data),
303 |     )
304 |     result = processor.process(data)
305 |     logger.info(
306 |         "Data processing completed",
307 |         input_count=len(data),
308 |         output_count=len(result),
309 |         items_modified=len(result) - len(data) if len(result) != len(data) else 0,
310 |         processing_status="success",
311 |     )
312 | 
313 |     return result
314 | 


--------------------------------------------------------------------------------
/scripts/setup.sh:
--------------------------------------------------------------------------------
  1 | #!/bin/bash
  2 | 
  3 | set -euo pipefail
  4 | 
  5 | # Colors for output
  6 | RED='\033[0;31m'
  7 | GREEN='\033[0;32m'
  8 | YELLOW='\033[1;33m'
  9 | NC='\033[0m' # No Color
 10 | 
 11 | # Default values
 12 | DEFAULT_PROJECT_NAME=$(basename "$(pwd)" | tr '[:upper:]' '[:lower:]' | tr '-' '_')
 13 | PYTHON_VERSION="3.12"
 14 | 
 15 | # Detect shell and set rc_file
 16 | rc_file="~/.bashrc"
 17 | if [[ "$SHELL" == "/bin/zsh" ]]; then
 18 |     rc_file=~/.zshrc
 19 | elif [[ "$SHELL" == "/bin/bash" ]]; then
 20 |     rc_file=~/.bashrc
 21 | elif [[ "$SHELL" == "/bin/fish" ]]; then
 22 |     rc_file=~/.config/fish/config.fish
 23 | else
 24 |     print_error "Failed to detect shell. Please set rc_file manually."
 25 | fi
 26 | 
 27 | # Functions
 28 | print_step() {
 29 |     echo -e "${GREEN}==>${NC} $1"
 30 | }
 31 | 
 32 | print_error() {
 33 |     echo -e "${RED}Error:${NC} $1" >&2
 34 | }
 35 | 
 36 | print_warning() {
 37 |     echo -e "${YELLOW}Warning:${NC} $1"
 38 | }
 39 | 
 40 | print_success() {
 41 |     echo -e "${GREEN}✓${NC} $1"
 42 | }
 43 | 
 44 | # Check if uv is installed
 45 | check_uv() {
 46 |     if ! command -v uv &> /dev/null; then
 47 |         print_error "uv is not installed."
 48 |         echo "Install it with: curl -LsSf https://astral.sh/uv/install.sh | sh"
 49 |         exit 1
 50 |     fi
 51 | }
 52 | 
 53 | check_npm() {
 54 |     if ! command -v npm &> /dev/null; then
 55 |         print_error "npm is not installed."
 56 |         # if macos, use nodebrew
 57 |         if [[ "$OSTYPE" == "darwin"* ]]; then
 58 |             print_step "Use nodebrew to install Node.js"
 59 |             if ! command -v nodebrew &> /dev/null; then
 60 |                 print_step "Install nodebrew"
 61 |                 brew install nodebrew
 62 |                 echo "export PATH=$HOME/.nodebrew/current/bin:$PATH" >> $rc_file
 63 |                 source $rc_file
 64 |             fi
 65 |             nodebrew install stable
 66 |             nodebrew use stable
 67 |             print_success "Node.js installed"
 68 |         elif [[ "$OSTYPE" == "linux"* ]]; then
 69 |             print_step "Use n to install Node.js"
 70 |             if ! command -v n &> /dev/null; then
 71 |                 print_step "Install n"
 72 |                 sudo apt update
 73 |                 sudo apt install -y nodejs npm
 74 |                 sudo npm install n -g
 75 |                 n stable
 76 |                 sudo apt purge -y nodejs npm
 77 |                 sudo apt autoremove -y
 78 |             fi
 79 |             n stable
 80 |             print_success "Node.js installed"
 81 |         else
 82 |             print_error "Unsupported OS. Please install Node.js manually."
 83 |         fi
 84 |     fi
 85 | }
 86 | 
 87 | check_github_cli() {
 88 |     if ! command -v gh &> /dev/null; then
 89 |         print_error "gh is not installed."
 90 |         print_step "Install gh"
 91 |         if [[ "$OSTYPE" == "darwin"* ]]; then
 92 |             brew install gh
 93 |             gh auth login
 94 |         elif [[ "$OSTYPE" == "linux"* ]]; then
 95 |             type -p curl >/dev/null || sudo apt install curl -y
 96 |             curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg \
 97 |             && sudo chmod go+r /usr/share/keyrings/githubcli-archive-keyring.gpg \
 98 |             && echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null \
 99 |             && sudo apt update \
100 |             && sudo apt install gh -y \
101 |             && gh auth login
102 |         fi
103 |         print_success "gh installed"
104 |     fi
105 | }
106 | 
107 | check_play_command() {
108 |     if ! command -v play &> /dev/null; then
109 |         print_warning "play command is not available. Installing sox for Claude Code hooks..."
110 |         if [[ "$OSTYPE" == "darwin"* ]]; then
111 |             print_step "Installing sox on macOS..."
112 |             brew install sox
113 |         elif [[ "$OSTYPE" == "linux"* ]]; then
114 |             print_step "Installing sox on Linux..."
115 |             sudo apt update
116 |             sudo apt install -y sox
117 |         else
118 |             print_warning "Unsupported OS for sox installation. Please install sox manually for Claude Code hooks."
119 |             return
120 |         fi
121 |         if command -v play &> /dev/null; then
122 |             print_success "play command installed successfully"
123 |         else
124 |             print_warning "Failed to install play command. Claude Code hooks may not work properly."
125 |         fi
126 |     else
127 |         print_success "play command already available"
128 |     fi
129 | }
130 | 
131 | check_claude_code() {
132 |     if ! command -v claude &> /dev/null; then
133 |         print_step "Installing Claude Code..."
134 |         sudo npm i -g @anthropic-ai/claude-code
135 |         print_success "Claude Code installed"
136 |         print_step "Checking Claude Code..."
137 |         claude --version
138 |         print_success "Claude Code checked"
139 |     fi
140 | }
141 | 
142 | check_gemini_cli() {
143 |     if ! command -v gemini &> /dev/null; then
144 |         print_step "Installing Gemini CLI..."
145 |         sudo npm install -g @google/gemini-cli
146 |         print_success "Gemini CLI installed"
147 |         print_step "Checking Gemini CLI..."
148 |         gemini --version
149 |         print_success "Gemini CLI checked"
150 |     fi
151 | }
152 | 
153 | # Get project name from user
154 | get_project_name() {
155 |     echo "Current directory: $(pwd)"
156 |     echo -n "Enter your project name (default: $DEFAULT_PROJECT_NAME): "
157 |     read -r PROJECT_NAME
158 | 
159 |     if [ -z "$PROJECT_NAME" ]; then
160 |         PROJECT_NAME=$DEFAULT_PROJECT_NAME
161 |     fi
162 | 
163 |     # Validate project name (Python package naming rules)
164 |     if ! echo "$PROJECT_NAME" | grep -qE '^[a-z][a-z0-9_]*$'; then
165 |         print_error "Invalid project name. Use lowercase letters, numbers, and underscores only."
166 |         print_error "Must start with a letter."
167 |         exit 1
168 |     fi
169 | 
170 |     echo "Project name: $PROJECT_NAME"
171 | }
172 | 
173 | # Update project name in all files
174 | update_project_name() {
175 |     print_step "Updating project name to '$PROJECT_NAME'..."
176 | 
177 |     # Use the Python script if it exists
178 |     if [ -f "scripts/update_project_name.py" ]; then
179 |         python scripts/update_project_name.py "$PROJECT_NAME"
180 |     else
181 |         # Fallback to manual replacement
182 |         # Update in specific files
183 |         for file in pyproject.toml README.md; do
184 |             if [ -f "$file" ]; then
185 |                 if [[ "$OSTYPE" == "darwin"* ]]; then
186 |                     # macOS
187 |                     sed -i '' "s/project_name/$PROJECT_NAME/g" "$file"
188 |                     sed -i '' "s/project-name/${PROJECT_NAME//_/-}/g" "$file"
189 |                 else
190 |                     # Linux
191 |                     sed -i "s/project_name/$PROJECT_NAME/g" "$file"
192 |                     sed -i "s/project-name/${PROJECT_NAME//_/-}/g" "$file"
193 |                 fi
194 |             fi
195 |         done
196 | 
197 |         # Rename directory
198 |         if [ -d "src/project_name" ]; then
199 |             mv "src/project_name" "src/$PROJECT_NAME"
200 |         fi
201 |     fi
202 | 
203 |     print_success "Project name updated"
204 | }
205 | 
206 | # Setup Python environment
207 | setup_python() {
208 |     print_step "Setting up Python environment..."
209 | 
210 |     # Pin Python version
211 |     uv python pin $PYTHON_VERSION
212 |     print_success "Python $PYTHON_VERSION pinned"
213 | 
214 |     # Install dependencies
215 |     print_step "Installing dependencies..."
216 |     uv sync --all-extras
217 |     print_success "Dependencies installed"
218 | }
219 | 
220 | # Setup pre-commit
221 | setup_precommit() {
222 |     print_step "Setting up pre-commit hooks..."
223 | 
224 |     uv run pre-commit install
225 |     uv run pre-commit install --hook-type commit-msg
226 | 
227 |     # Run pre-commit on all files to ensure everything is set up
228 |     print_step "Running initial pre-commit checks..."
229 |     uv run pre-commit run --all-files || true
230 | 
231 |     print_success "Pre-commit hooks installed"
232 | }
233 | 
234 | # Initialize git if needed
235 | init_git() {
236 |     if [ ! -d ".git" ]; then
237 |         print_step "Initializing git repository..."
238 |         git init
239 |         git add .
240 |         git commit -m "Initial commit from python-claude-template"
241 |         print_success "Git repository initialized"
242 |     else
243 |         print_success "Git repository already exists"
244 |     fi
245 | }
246 | 
247 | # Run initial tests
248 | run_tests() {
249 |     print_step "Running initial tests..."
250 | 
251 |     if uv run pytest tests/ -v; then
252 |         print_success "All tests passed!"
253 |     else
254 |         print_warning "Some tests failed. This is expected for a new project."
255 |     fi
256 | }
257 | 
258 | # Main setup flow
259 | main() {
260 |     echo "🚀 Python Claude Template Setup"
261 |     echo "==============================="
262 |     echo
263 | 
264 |     # Check prerequisites
265 |     check_uv
266 |     check_npm
267 |     check_claude_code
268 |     check_gemini_cli
269 |     check_github_cli
270 |     check_play_command
271 | 
272 |     # Rename project if needed
273 |     if [ -d "src/project_name" ]; then
274 |         get_project_name
275 |         echo
276 |         update_project_name
277 |     fi
278 | 
279 |     # Perform setup
280 |     setup_python
281 |     setup_precommit
282 |     init_git
283 |     run_tests
284 | 
285 |     echo
286 |     echo "✨ Setup complete!"
287 |     echo
288 |     echo "Next steps:"
289 |     echo "1. Authorize Claude Code and Gemini CLI"
290 |     echo "2. Initialize project via `/initialize-project` via Claude Code"
291 |     echo "3. Set up branch protection (optional):"
292 |     echo "   gh repo view --web  # Open in browser to configure"
293 |     echo "4. Start coding! 🎉"
294 |     echo
295 |     echo "Useful commands:"
296 |     echo "  make test              # Run tests"
297 |     echo "  make format            # Format code"
298 |     echo "  make lint              # Lint code"
299 |     echo "  make typecheck         # Type check"
300 |     echo "  make check             # Run all checks"
301 |     echo "  make help              # Show all available commands"
302 |     echo "  uv add <package>       # Add a dependency"
303 |     echo "  make pr                # Create pull request"
304 |     echo "  make issue-bug         # Create bug report"
305 |     echo "  make issue-feature     # Create feature request"
306 |     echo "  make issue-claude      # Create Claude Code collaboration issue"
307 |     echo "  make issue             # Create issue (template selection)"
308 |     echo
309 | }
310 | 
311 | # Run main function
312 | main
313 | 


--------------------------------------------------------------------------------
/template/tests/unit/test_logging.py:
--------------------------------------------------------------------------------
  1 | """Unit tests for structured logging functionality."""
  2 | 
  3 | import json
  4 | import logging
  5 | import os
  6 | from pathlib import Path
  7 | 
  8 | import pytest
  9 | import structlog
 10 | from structlog.testing import LogCapture
 11 | from template_package.utils.logging_config import (
 12 |     get_logger,
 13 |     log_context,
 14 |     log_performance,
 15 |     set_log_level,
 16 |     setup_logging,
 17 | )
 18 | 
 19 | 
 20 | @pytest.fixture
 21 | def log_capture() -> LogCapture:
 22 |     """Fixture for capturing structured logs in tests."""
 23 |     return LogCapture()
 24 | 
 25 | 
 26 | @pytest.fixture
 27 | def configure_test_logging(log_capture: LogCapture) -> None:
 28 |     """Configure structlog for testing with log capture."""
 29 |     structlog.configure(
 30 |         processors=[
 31 |             structlog.stdlib.add_log_level,
 32 |             structlog.processors.dict_tracebacks,
 33 |             log_capture,
 34 |         ],
 35 |         wrapper_class=structlog.stdlib.BoundLogger,
 36 |         logger_factory=structlog.stdlib.LoggerFactory(),
 37 |         cache_logger_on_first_use=False,
 38 |     )
 39 | 
 40 | 
 41 | class TestStructuredLogging:
 42 |     """Test structured logging configuration and usage."""
 43 | 
 44 |     def test_正常系_基本的なロギングが動作する(
 45 |         self,
 46 |         configure_test_logging: None,
 47 |         log_capture: LogCapture,
 48 |     ) -> None:
 49 |         """基本的なロギング機能が正しく動作することを確認。"""
 50 |         logger = get_logger(__name__)
 51 | 
 52 |         logger.info("Test message", key1="value1", key2=42)
 53 | 
 54 |         assert len(log_capture.entries) == 1
 55 |         entry = log_capture.entries[0]
 56 |         assert entry["log_level"] == "info"
 57 |         assert entry["event"] == "Test message"
 58 |         assert entry["key1"] == "value1"
 59 |         assert entry["key2"] == 42
 60 | 
 61 |     def test_正常系_コンテキスト付きロガーが動作する(
 62 |         self,
 63 |         configure_test_logging: None,
 64 |         log_capture: LogCapture,
 65 |     ) -> None:
 66 |         """コンテキスト付きロガーが正しく動作することを確認。"""
 67 |         logger = get_logger(__name__, module="test_module", version="1.0")
 68 | 
 69 |         logger.debug("Debug message", operation="test")
 70 | 
 71 |         assert len(log_capture.entries) == 1
 72 |         entry = log_capture.entries[0]
 73 |         assert entry["module"] == "test_module"
 74 |         assert entry["version"] == "1.0"
 75 |         assert entry["operation"] == "test"
 76 | 
 77 |     def test_正常系_ログコンテキストマネージャが動作する(
 78 |         self,
 79 |         configure_test_logging: None,
 80 |         log_capture: LogCapture,
 81 |     ) -> None:
 82 |         """ログコンテキストマネージャーが正しく動作することを確認。"""
 83 |         logger = get_logger(__name__)
 84 | 
 85 |         # コンテキストが正しく動作することの確認（レコードのみチェック）
 86 |         with log_context(user_id=123, request_id="abc"):
 87 |             logger.info("Inside context")
 88 | 
 89 |         logger.info("Outside context")
 90 | 
 91 |         assert len(log_capture.entries) == 2
 92 |         # Note: log_contextはcontextvarsを使用するため、LogCaptureでは
 93 |         # コンテキスト変数が正しくキャプチャされない可能性がある
 94 |         # ここでは正常にログが出力されることのみ確認
 95 | 
 96 |     def test_正常系_ログレベルが正しく動作する(
 97 |         self,
 98 |         configure_test_logging: None,
 99 |         log_capture: LogCapture,
100 |     ) -> None:
101 |         """各ログレベルが正しく動作することを確認。"""
102 |         logger = get_logger(__name__)
103 | 
104 |         logger.debug("Debug message")
105 |         logger.info("Info message")
106 |         logger.warning("Warning message")
107 |         logger.error("Error message")
108 |         logger.critical("Critical message")
109 | 
110 |         assert len(log_capture.entries) == 5
111 | 
112 |         levels = [entry["log_level"] for entry in log_capture.entries]
113 |         assert levels == ["debug", "info", "warning", "error", "critical"]
114 | 
115 |     def test_正常系_ログレベルの動的変更が動作する(
116 |         self,
117 |         tmp_path: Path,
118 |     ) -> None:
119 |         """ログレベルの動的変更が正しく動作することを確認。"""
120 |         # 一時ファイルにログを出力
121 |         log_file = tmp_path / "test.log"
122 | 
123 |         # INFOレベルで初期化
124 |         setup_logging(level="INFO", format="json", log_file=log_file, force=True)
125 | 
126 |         # ログレベルをWARNINGに変更
127 |         set_log_level("WARNING")
128 | 
129 |         # 標準ライブラリのロガーで確認
130 |         assert logging.root.level == logging.WARNING
131 | 
132 |     def test_正常系_パフォーマンスデコレータが動作する(
133 |         self,
134 |         configure_test_logging: None,
135 |         log_capture: LogCapture,
136 |     ) -> None:
137 |         """パフォーマンスログデコレータが正しく動作することを確認。"""
138 |         logger = get_logger(__name__)
139 | 
140 |         @log_performance(logger)
141 |         def test_function(x: int, y: int) -> int:
142 |             return x + y
143 | 
144 |         result = test_function(10, 20)
145 | 
146 |         assert result == 30
147 |         assert len(log_capture.entries) == 2
148 | 
149 |         # 開始ログ
150 |         start_entry = log_capture.entries[0]
151 |         assert "started" in start_entry["event"]
152 |         assert start_entry["function"] == "test_function"
153 |         assert start_entry["args_count"] == 2
154 | 
155 |         # 完了ログ
156 |         end_entry = log_capture.entries[1]
157 |         assert "completed" in end_entry["event"]
158 |         assert end_entry["function"] == "test_function"
159 |         assert "duration_ms" in end_entry
160 |         assert end_entry["success"] is True
161 | 
162 |     def test_異常系_パフォーマンスデコレータでエラーが記録される(
163 |         self,
164 |         configure_test_logging: None,
165 |         log_capture: LogCapture,
166 |     ) -> None:
167 |         """パフォーマンスデコレータでエラーが正しく記録されることを確認。"""
168 |         logger = get_logger(__name__)
169 | 
170 |         @log_performance(logger)
171 |         def failing_function() -> None:
172 |             raise ValueError("Test error")
173 | 
174 |         with pytest.raises(ValueError, match="Test error"):
175 |             failing_function()
176 | 
177 |         assert len(log_capture.entries) == 2
178 | 
179 |         # エラーログ
180 |         error_entry = log_capture.entries[1]
181 |         assert "failed" in error_entry["event"]
182 |         assert error_entry["success"] is False
183 |         assert error_entry["error_type"] == "ValueError"
184 |         assert error_entry["error_message"] == "Test error"
185 | 
186 |     def test_正常系_JSON形式で出力される(
187 |         self,
188 |         tmp_path: Path,
189 |     ) -> None:
190 |         """JSON形式でログが出力されることを確認。"""
191 |         log_file = tmp_path / "test.json"
192 | 
193 |         # structlogでJSON形式の設定
194 |         setup_logging(
195 |             level="INFO",
196 |             format="json",
197 |             log_file=log_file,
198 |             include_timestamp=True,
199 |             include_caller_info=True,
200 |             force=True,
201 |         )
202 | 
203 |         logger = get_logger(__name__)
204 |         logger.info(
205 |             "Test JSON output",
206 |             test_key="test_value",
207 |             number=42,
208 |             boolean=True,
209 |         )
210 | 
211 |         # ファイルが作成されることを確認
212 |         assert log_file.exists()
213 |         content = log_file.read_text().strip()
214 | 
215 |         # JSON形式であることを確認
216 |         try:
217 |             # ファイルから読み取った内容をJSONとして解析
218 |             log_data = json.loads(content)
219 | 
220 |             # 基本的なログ内容を確認
221 |             assert log_data["event"] == "Test JSON output"
222 |             assert log_data["test_key"] == "test_value"
223 |             assert log_data["number"] == 42
224 |             assert log_data["boolean"] is True
225 | 
226 |             # structlog特有のフィールドを確認
227 |             assert "timestamp" in log_data
228 |             assert "level" in log_data
229 |             assert log_data["level"] == "INFO"
230 |             assert "logger" in log_data
231 |             assert log_data["logger"] == "unit.test_logging"
232 | 
233 |             # caller情報も含まれることを確認
234 |             assert "caller" in log_data
235 |             assert isinstance(log_data["caller"], dict)
236 |             assert "filename" in log_data["caller"]
237 |             assert "function" in log_data["caller"]
238 |             assert "line" in log_data["caller"]
239 |             assert log_data["caller"]["filename"] == "test_logging.py"
240 | 
241 |         except json.JSONDecodeError as e:
242 |             pytest.fail(f"Log output is not valid JSON: {e}\nContent: {content}")
243 | 
244 |     def test_正常系_複数のコンテキストがネストできる(
245 |         self,
246 |         configure_test_logging: None,
247 |         log_capture: LogCapture,
248 |     ) -> None:
249 |         """複数のコンテキストがネストして動作することを確認。"""
250 |         logger = get_logger(__name__)
251 | 
252 |         # ネストしたコンテキストが例外なく動作することを確認
253 |         with log_context(level1="value1"):
254 |             logger.info("Level 1 context")
255 | 
256 |             with log_context(level2="value2"):
257 |                 logger.info("Level 2 context")
258 | 
259 |             logger.info("Back to level 1")
260 | 
261 |         logger.info("No context")
262 | 
263 |         # 4つのログが出力されることを確認
264 |         assert len(log_capture.entries) == 4
265 | 
266 |     def test_正常系_構造化データが保持される(
267 |         self,
268 |         configure_test_logging: None,
269 |         log_capture: LogCapture,
270 |     ) -> None:
271 |         """複雑な構造化データが正しく保持されることを確認。"""
272 |         logger = get_logger(__name__)
273 | 
274 |         complex_data = {
275 |             "user": {"id": 123, "name": "Test User"},
276 |             "items": [1, 2, 3],
277 |             "metadata": {"version": "1.0", "timestamp": 1234567890},
278 |         }
279 | 
280 |         logger.info("Complex data test", **complex_data)
281 | 
282 |         assert len(log_capture.entries) == 1
283 |         entry = log_capture.entries[0]
284 | 
285 |         assert entry["user"] == {"id": 123, "name": "Test User"}
286 |         assert entry["items"] == [1, 2, 3]
287 |         assert entry["metadata"] == {"version": "1.0", "timestamp": 1234567890}
288 | 
289 |     def test_正常系_例外情報が構造化される(
290 |         self,
291 |         configure_test_logging: None,
292 |         log_capture: LogCapture,
293 |     ) -> None:
294 |         """例外情報が構造化されて記録されることを確認。"""
295 |         logger = get_logger(__name__)
296 | 
297 |         try:
298 |             raise ValueError("Test exception")
299 |         except ValueError:
300 |             logger.error("Exception occurred", exc_info=True)
301 | 
302 |         assert len(log_capture.entries) == 1
303 |         entry = log_capture.entries[0]
304 | 
305 |         assert entry["log_level"] == "error"
306 |         # exc_infoまたはexceptionフィールドがあることを確認
307 |         assert "exc_info" in entry or "exception" in entry
308 | 
309 | 
310 | class TestLoggingConfiguration:
311 |     """Test logging configuration options."""
312 | 
313 |     def test_正常系_環境変数からログレベルが設定される(
314 |         self,
315 |         monkeypatch: pytest.MonkeyPatch,
316 |         tmp_path: Path,
317 |     ) -> None:
318 |         """環境変数からログレベルが正しく設定されることを確認。"""
319 |         monkeypatch.setenv("LOG_LEVEL", "DEBUG")
320 |         monkeypatch.setenv("LOG_FORMAT", "json")
321 | 
322 |         log_file = tmp_path / "test.log"
323 |         setup_logging(log_file=log_file, force=True)
324 | 
325 |         # ログレベルがDEBUGになっていることを確認
326 |         assert logging.root.level == logging.DEBUG
327 | 
328 |     def test_正常系_カスタムロガー名でレベル変更できる(
329 |         self,
330 |         tmp_path: Path,
331 |     ) -> None:
332 |         """特定のロガーのレベルのみ変更できることを確認。"""
333 |         setup_logging(level="INFO", force=True)
334 | 
335 |         # 特定のロガーのみWARNINGに変更
336 |         set_log_level("WARNING", logger_name="template_package.core")
337 | 
338 |         # 確認
339 |         assert logging.getLogger("template_package.core").level == logging.WARNING
340 |         assert logging.root.level == logging.INFO
341 | 
342 |     def test_正常系_開発環境でコンソール出力が有効(
343 |         self,
344 |         monkeypatch: pytest.MonkeyPatch,
345 |     ) -> None:
346 |         """開発環境でコンソール出力が有効になることを確認。"""
347 |         monkeypatch.setenv("PROJECT_ENV", "development")
348 | 
349 |         # setup_logging は既に開発環境用の設定で呼ばれる
350 |         # ここでは環境変数が正しく設定されていることを確認
351 |         assert os.environ.get("PROJECT_ENV") == "development"
352 | 


--------------------------------------------------------------------------------
/template/tests/unit/test_helpers.py:
--------------------------------------------------------------------------------
  1 | """Unit tests for utility helper functions."""
  2 | 
  3 | import json
  4 | from pathlib import Path
  5 | from typing import Any
  6 | 
  7 | import pytest
  8 | from template_package.utils.helpers import (
  9 |     chunk_list,
 10 |     flatten_dict,
 11 |     load_json_file,
 12 |     save_json_file,
 13 | )
 14 | 
 15 | 
 16 | class TestLoadJsonFile:
 17 |     """Test load_json_file function."""
 18 | 
 19 |     def test_正常系_有効なJSONファイルを読み込める(
 20 |         self,
 21 |         temp_dir: Path,
 22 |     ) -> None:
 23 |         """有効なJSONファイルを正常に読み込めることを確認。"""
 24 |         test_data = {"name": "test", "value": 123, "nested": {"key": "value"}}
 25 |         json_file = temp_dir / "test.json"
 26 |         json_file.write_text(json.dumps(test_data), encoding="utf-8")
 27 | 
 28 |         result = load_json_file(json_file)
 29 | 
 30 |         assert result == test_data
 31 |         assert isinstance(result, dict)
 32 | 
 33 |     def test_正常系_Path型とstr型の両方を受け付ける(
 34 |         self,
 35 |         temp_dir: Path,
 36 |     ) -> None:
 37 |         """Path型とstr型の両方のパスを受け付けることを確認。"""
 38 |         test_data = {"test": "data"}
 39 |         json_file = temp_dir / "test.json"
 40 |         json_file.write_text(json.dumps(test_data), encoding="utf-8")
 41 | 
 42 |         # Path型での読み込み
 43 |         result_path = load_json_file(json_file)
 44 |         # str型での読み込み
 45 |         result_str = load_json_file(str(json_file))
 46 | 
 47 |         assert result_path == test_data
 48 |         assert result_str == test_data
 49 | 
 50 |     def test_異常系_ファイルが存在しない場合FileNotFoundError(
 51 |         self,
 52 |         temp_dir: Path,
 53 |     ) -> None:
 54 |         """存在しないファイルを読み込もうとするとFileNotFoundErrorが発生。"""
 55 |         non_existent_file = temp_dir / "non_existent.json"
 56 | 
 57 |         with pytest.raises(FileNotFoundError, match="File not found"):
 58 |             load_json_file(non_existent_file)
 59 | 
 60 |     def test_異常系_無効なJSONでValueError(
 61 |         self,
 62 |         temp_dir: Path,
 63 |     ) -> None:
 64 |         """無効なJSONファイルを読み込もうとするとValueErrorが発生。"""
 65 |         invalid_json_file = temp_dir / "invalid.json"
 66 |         invalid_json_file.write_text("{invalid json}", encoding="utf-8")
 67 | 
 68 |         with pytest.raises(ValueError, match="Invalid JSON"):
 69 |             load_json_file(invalid_json_file)
 70 | 
 71 |     def test_異常系_JSONが辞書でない場合ValueError(
 72 |         self,
 73 |         temp_dir: Path,
 74 |     ) -> None:
 75 |         """JSONが辞書でない場合、ValueErrorが発生。"""
 76 |         json_file = temp_dir / "array.json"
 77 |         json_file.write_text("[1, 2, 3]", encoding="utf-8")
 78 | 
 79 |         with pytest.raises(ValueError, match="Expected JSON object.*got list"):
 80 |             load_json_file(json_file)
 81 | 
 82 |     def test_エッジケース_空の辞書を読み込める(
 83 |         self,
 84 |         temp_dir: Path,
 85 |     ) -> None:
 86 |         """空の辞書を含むJSONファイルを読み込めることを確認。"""
 87 |         json_file = temp_dir / "empty.json"
 88 |         json_file.write_text("{}", encoding="utf-8")
 89 | 
 90 |         result = load_json_file(json_file)
 91 | 
 92 |         assert result == {}
 93 |         assert isinstance(result, dict)
 94 | 
 95 |     def test_正常系_日本語を含むJSONを読み込める(
 96 |         self,
 97 |         temp_dir: Path,
 98 |     ) -> None:
 99 |         """日本語を含むJSONファイルを正常に読み込めることを確認。"""
100 |         test_data = {"名前": "テスト", "説明": "これはテストです"}
101 |         json_file = temp_dir / "japanese.json"
102 |         json_file.write_text(
103 |             json.dumps(test_data, ensure_ascii=False), encoding="utf-8"
104 |         )
105 | 
106 |         result = load_json_file(json_file)
107 | 
108 |         assert result == test_data
109 | 
110 | 
111 | class TestSaveJsonFile:
112 |     """Test save_json_file function."""
113 | 
114 |     def test_正常系_JSONファイルを保存できる(
115 |         self,
116 |         temp_dir: Path,
117 |     ) -> None:
118 |         """辞書データをJSONファイルとして保存できることを確認。"""
119 |         test_data = {"name": "test", "value": 123, "nested": {"key": "value"}}
120 |         json_file = temp_dir / "output.json"
121 | 
122 |         save_json_file(test_data, json_file)
123 | 
124 |         assert json_file.exists()
125 |         loaded_data = json.loads(json_file.read_text(encoding="utf-8"))
126 |         assert loaded_data == test_data
127 | 
128 |     def test_正常系_親ディレクトリが自動作成される(
129 |         self,
130 |         temp_dir: Path,
131 |     ) -> None:
132 |         """親ディレクトリが存在しない場合、自動的に作成されることを確認。"""
133 |         test_data = {"test": "data"}
134 |         nested_path = temp_dir / "nested" / "dir" / "output.json"
135 | 
136 |         save_json_file(test_data, nested_path)
137 | 
138 |         assert nested_path.exists()
139 |         assert nested_path.parent.exists()
140 | 
141 |     def test_正常系_カスタムインデントで保存できる(
142 |         self,
143 |         temp_dir: Path,
144 |     ) -> None:
145 |         """カスタムインデントレベルでJSONを保存できることを確認。"""
146 |         test_data = {"test": "data", "nested": {"key": "value"}}
147 |         json_file = temp_dir / "indented.json"
148 | 
149 |         save_json_file(test_data, json_file, indent=4)
150 | 
151 |         content = json_file.read_text(encoding="utf-8")
152 |         assert "    " in content  # 4スペースのインデント
153 | 
154 |     def test_正常系_日本語を含むデータを保存できる(
155 |         self,
156 |         temp_dir: Path,
157 |     ) -> None:
158 |         """日本語を含むデータを正しく保存できることを確認。"""
159 |         test_data = {"名前": "テスト", "説明": "これはテストです"}
160 |         json_file = temp_dir / "japanese.json"
161 | 
162 |         save_json_file(test_data, json_file, ensure_ascii=False)
163 | 
164 |         content = json_file.read_text(encoding="utf-8")
165 |         assert "名前" in content
166 |         assert "\\u" not in content  # Unicodeエスケープされていない
167 | 
168 |     def test_正常系_既存ファイルを上書きできる(
169 |         self,
170 |         temp_dir: Path,
171 |     ) -> None:
172 |         """既存のファイルを上書きできることを確認。"""
173 |         json_file = temp_dir / "existing.json"
174 |         json_file.write_text('{"old": "data"}', encoding="utf-8")
175 |         new_data = {"new": "data"}
176 | 
177 |         save_json_file(new_data, json_file)
178 | 
179 |         loaded_data = json.loads(json_file.read_text(encoding="utf-8"))
180 |         assert loaded_data == new_data
181 | 
182 | 
183 | class TestChunkList:
184 |     """Test chunk_list function."""
185 | 
186 |     def test_正常系_リストを指定サイズに分割できる(self) -> None:
187 |         """リストを指定サイズのチャンクに分割できることを確認。"""
188 |         items = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
189 | 
190 |         chunks = chunk_list(items, 3)
191 | 
192 |         assert chunks == [[1, 2, 3], [4, 5, 6], [7, 8, 9], [10]]
193 | 
194 |     def test_正常系_ちょうど割り切れるサイズで分割できる(self) -> None:
195 |         """リストがチャンクサイズで割り切れる場合の動作を確認。"""
196 |         items = [1, 2, 3, 4, 5, 6]
197 | 
198 |         chunks = chunk_list(items, 2)
199 | 
200 |         assert chunks == [[1, 2], [3, 4], [5, 6]]
201 | 
202 |     def test_正常系_チャンクサイズがリストより大きい場合(self) -> None:
203 |         """チャンクサイズがリストサイズより大きい場合の動作を確認。"""
204 |         items = [1, 2, 3]
205 | 
206 |         chunks = chunk_list(items, 10)
207 | 
208 |         assert chunks == [[1, 2, 3]]
209 | 
210 |     def test_正常系_空のリストを処理できる(self) -> None:
211 |         """空のリストを処理できることを確認。"""
212 |         items: list[int] = []
213 | 
214 |         chunks = chunk_list(items, 5)
215 | 
216 |         assert chunks == []
217 | 
218 |     def test_正常系_異なる型のリストを処理できる(self) -> None:
219 |         """文字列リストなど異なる型でも動作することを確認。"""
220 |         items = ["a", "b", "c", "d", "e"]
221 | 
222 |         chunks = chunk_list(items, 2)
223 | 
224 |         assert chunks == [["a", "b"], ["c", "d"], ["e"]]
225 | 
226 |     def test_異常系_チャンクサイズが0以下でValueError(self) -> None:
227 |         """チャンクサイズが0以下の場合、ValueErrorが発生。"""
228 |         items = [1, 2, 3]
229 | 
230 |         with pytest.raises(ValueError, match="chunk_size must be positive"):
231 |             chunk_list(items, 0)
232 | 
233 |         with pytest.raises(ValueError, match="chunk_size must be positive"):
234 |             chunk_list(items, -1)
235 | 
236 |     @pytest.mark.parametrize(
237 |         "input_size,chunk_size,expected_chunks",
238 |         [
239 |             (10, 1, 10),  # 1要素ずつ
240 |             (10, 5, 2),  # 半分ずつ
241 |             (10, 10, 1),  # 全体で1チャンク
242 |             (10, 15, 1),  # チャンクサイズが大きい
243 |             (0, 5, 0),  # 空リスト
244 |         ],
245 |     )
246 |     def test_パラメトライズ_様々なサイズで正しくチャンク数が計算される(
247 |         self,
248 |         input_size: int,
249 |         chunk_size: int,
250 |         expected_chunks: int,
251 |     ) -> None:
252 |         """様々なサイズの組み合わせで正しいチャンク数になることを確認。"""
253 |         items = list(range(input_size))
254 | 
255 |         chunks = chunk_list(items, chunk_size)
256 | 
257 |         assert len(chunks) == expected_chunks
258 | 
259 | 
260 | class TestFlattenDict:
261 |     """Test flatten_dict function."""
262 | 
263 |     def test_正常系_ネストした辞書をフラット化できる(self) -> None:
264 |         """ネストした辞書を正しくフラット化できることを確認。"""
265 |         nested = {
266 |             "a": 1,
267 |             "b": {
268 |                 "c": 2,
269 |                 "d": {
270 |                     "e": 3,
271 |                 },
272 |             },
273 |         }
274 | 
275 |         flattened = flatten_dict(nested)
276 | 
277 |         assert flattened == {
278 |             "a": 1,
279 |             "b.c": 2,
280 |             "b.d.e": 3,
281 |         }
282 | 
283 |     def test_正常系_カスタムセパレータを使用できる(self) -> None:
284 |         """カスタムセパレータでフラット化できることを確認。"""
285 |         nested = {
286 |             "a": {
287 |                 "b": 1,
288 |                 "c": 2,
289 |             },
290 |         }
291 | 
292 |         flattened = flatten_dict(nested, separator="/")
293 | 
294 |         assert flattened == {
295 |             "a/b": 1,
296 |             "a/c": 2,
297 |         }
298 | 
299 |     def test_正常系_プレフィックスを追加できる(self) -> None:
300 |         """プレフィックスを追加してフラット化できることを確認。"""
301 |         nested = {
302 |             "a": 1,
303 |             "b": {
304 |                 "c": 2,
305 |             },
306 |         }
307 | 
308 |         flattened = flatten_dict(nested, prefix="root")
309 | 
310 |         assert flattened == {
311 |             "root.a": 1,
312 |             "root.b.c": 2,
313 |         }
314 | 
315 |     def test_正常系_空の辞書を処理できる(self) -> None:
316 |         """空の辞書を処理できることを確認。"""
317 |         flattened = flatten_dict({})
318 | 
319 |         assert flattened == {}
320 | 
321 |     def test_正常系_フラットな辞書はそのまま返される(self) -> None:
322 |         """既にフラットな辞書はそのまま返されることを確認。"""
323 |         flat_dict = {"a": 1, "b": 2, "c": 3}
324 | 
325 |         flattened = flatten_dict(flat_dict)
326 | 
327 |         assert flattened == flat_dict
328 | 
329 |     def test_正常系_混在した型を含む辞書を処理できる(self) -> None:
330 |         """様々な型の値を含む辞書を処理できることを確認。"""
331 |         nested: dict[str, Any] = {
332 |             "string": "value",
333 |             "number": 123,
334 |             "float": 3.14,
335 |             "bool": True,
336 |             "none": None,
337 |             "list": [1, 2, 3],
338 |             "nested": {
339 |                 "key": "value",
340 |             },
341 |         }
342 | 
343 |         flattened = flatten_dict(nested)
344 | 
345 |         assert flattened == {
346 |             "string": "value",
347 |             "number": 123,
348 |             "float": 3.14,
349 |             "bool": True,
350 |             "none": None,
351 |             "list": [1, 2, 3],
352 |             "nested.key": "value",
353 |         }
354 | 
355 |     def test_正常系_深いネストを処理できる(self) -> None:
356 |         """深くネストした辞書を処理できることを確認。"""
357 |         nested = {
358 |             "level1": {
359 |                 "level2": {
360 |                     "level3": {
361 |                         "level4": {
362 |                             "value": "deep",
363 |                         },
364 |                     },
365 |                 },
366 |             },
367 |         }
368 | 
369 |         flattened = flatten_dict(nested)
370 | 
371 |         assert flattened == {
372 |             "level1.level2.level3.level4.value": "deep",
373 |         }
374 | 
375 |     def test_正常系_同じキーが異なるレベルに存在する場合(self) -> None:
376 |         """同じキー名が異なるネストレベルに存在する場合の動作を確認。"""
377 |         nested = {
378 |             "data": 1,
379 |             "group": {
380 |                 "data": 2,
381 |                 "subgroup": {
382 |                     "data": 3,
383 |                 },
384 |             },
385 |         }
386 | 
387 |         flattened = flatten_dict(nested)
388 | 
389 |         assert flattened == {
390 |             "data": 1,
391 |             "group.data": 2,
392 |             "group.subgroup.data": 3,
393 |         }
394 | 


--------------------------------------------------------------------------------
/src/project_name/utils/logging_config.py:
--------------------------------------------------------------------------------
  1 | """Structured logging configuration using structlog."""
  2 | 
  3 | import logging
  4 | import os
  5 | import sys
  6 | from collections.abc import Iterator
  7 | from contextlib import contextmanager
  8 | from datetime import UTC, datetime
  9 | from pathlib import Path
 10 | from typing import Any, Protocol
 11 | 
 12 | import structlog
 13 | from structlog import BoundLogger
 14 | from structlog.contextvars import (
 15 |     bind_contextvars,
 16 |     unbind_contextvars,
 17 | )
 18 | 
 19 | from ..types import LogFormat, LogLevel
 20 | 
 21 | 
 22 | class LoggerProtocol(Protocol):
 23 |     """Protocol for structured logger."""
 24 | 
 25 |     def bind(self, **kwargs: Any) -> "LoggerProtocol":
 26 |         """Bind context variables to the logger."""
 27 |         ...
 28 | 
 29 |     def unbind(self, *keys: str) -> "LoggerProtocol":
 30 |         """Unbind context variables from the logger."""
 31 |         ...
 32 | 
 33 |     def debug(self, event: str, **kwargs: Any) -> None:
 34 |         """Log a debug message."""
 35 |         ...
 36 | 
 37 |     def info(self, event: str, **kwargs: Any) -> None:
 38 |         """Log an info message."""
 39 |         ...
 40 | 
 41 |     def warning(self, event: str, **kwargs: Any) -> None:
 42 |         """Log a warning message."""
 43 |         ...
 44 | 
 45 |     def error(self, event: str, **kwargs: Any) -> None:
 46 |         """Log an error message."""
 47 |         ...
 48 | 
 49 |     def critical(self, event: str, **kwargs: Any) -> None:
 50 |         """Log a critical message."""
 51 |         ...
 52 | 
 53 | 
 54 | def add_timestamp(_: Any, __: Any, event_dict: dict[str, Any]) -> dict[str, Any]:
 55 |     """Add ISO timestamp to log entries."""
 56 |     event_dict["timestamp"] = datetime.now(UTC).isoformat()
 57 |     return event_dict
 58 | 
 59 | 
 60 | def add_caller_info(_: Any, __: Any, event_dict: dict[str, Any]) -> dict[str, Any]:
 61 |     """Add caller information (file, function, line) to log entries."""
 62 |     try:
 63 |         # Get the caller frame (skip structlog internals)
 64 |         import inspect
 65 | 
 66 |         frame = None
 67 |         stack = inspect.stack()
 68 | 
 69 |         # Skip the first few frames which are structlog internals
 70 |         for f in stack[4:12]:  # Limit search to avoid infinite loops
 71 |             if f.filename and f.function:
 72 |                 module = inspect.getmodule(f.frame)
 73 |                 if (
 74 |                     module
 75 |                     and not module.__name__.startswith("structlog")
 76 |                     and not module.__name__.startswith("logging")
 77 |                     and "site-packages" not in f.filename
 78 |                 ):
 79 |                     frame = f
 80 |                     break
 81 | 
 82 |         if frame:
 83 |             event_dict["caller"] = {
 84 |                 "filename": Path(frame.filename).name,
 85 |                 "function": frame.function,
 86 |                 "line": frame.lineno,
 87 |             }
 88 |     except Exception:  # nosec B110
 89 |         # If caller info extraction fails, silently continue
 90 |         # This is intentional to prevent logging infrastructure failures
 91 |         pass
 92 | 
 93 |     return event_dict
 94 | 
 95 | 
 96 | def add_log_level_upper(_: Any, __: Any, event_dict: dict[str, Any]) -> dict[str, Any]:
 97 |     """Convert log level to uppercase for consistency."""
 98 |     if "level" in event_dict:
 99 |         event_dict["level"] = event_dict["level"].upper()
100 |     return event_dict
101 | 
102 | 
103 | def setup_logging(
104 |     *,
105 |     level: LogLevel | str = "INFO",
106 |     format: LogFormat = "console",
107 |     log_file: str | Path | None = None,
108 |     include_timestamp: bool = True,
109 |     include_caller_info: bool = True,
110 |     force: bool = False,
111 | ) -> None:
112 |     """Setup structured logging configuration.
113 | 
114 |     Parameters
115 |     ----------
116 |     level : LogLevel | str
117 |         Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
118 |         Can also be set via LOG_LEVEL environment variable
119 |     format : LogFormat
120 |         Output format: "json", "console", or "plain"
121 |         - json: Structured JSON output (best for production)
122 |         - console: Colored, human-readable output (best for development)
123 |         - plain: Simple key=value output
124 |     log_file : str | Path | None
125 |         Optional file path to write logs to
126 |     include_timestamp : bool
127 |         Whether to add ISO timestamps to logs
128 |     include_caller_info : bool
129 |         Whether to add caller information (file, function, line)
130 |     force : bool
131 |         Force reconfiguration even if already configured
132 |     """
133 |     # 環境変数からログレベルを取得
134 |     env_level = os.environ.get("LOG_LEVEL", "").upper()
135 |     if env_level in ["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]:
136 |         level = env_level
137 | 
138 |     # 環境変数からフォーマットを取得
139 |     env_format = os.environ.get("LOG_FORMAT", "").lower()
140 |     if env_format in ["json", "console", "plain"]:
141 |         format = env_format  # type: ignore
142 | 
143 |     # プロセッサの設定
144 |     processors: list[Any] = [
145 |         structlog.contextvars.merge_contextvars,
146 |         structlog.stdlib.filter_by_level,
147 |         structlog.stdlib.add_logger_name,
148 |         structlog.stdlib.add_log_level,
149 |         structlog.stdlib.PositionalArgumentsFormatter(),
150 |         add_log_level_upper,
151 |         structlog.processors.StackInfoRenderer(),
152 |         structlog.processors.format_exc_info,
153 |     ]
154 | 
155 |     # Add timestamp processor if enabled
156 |     if include_timestamp:
157 |         processors.insert(3, add_timestamp)
158 | 
159 |     # Add caller info processor if enabled
160 |     if include_caller_info:
161 |         processors.insert(4, add_caller_info)
162 | 
163 |     # 開発環境判定
164 |     is_development = (
165 |         os.environ.get("PROJECT_ENV") == "development" or format == "console"
166 |     )
167 | 
168 |     # レンダラーの選択
169 |     if format == "json":
170 |         processors.append(structlog.processors.JSONRenderer())
171 |     elif format == "console" and is_development:
172 |         try:
173 |             # Rich ConsoleRendererを使用（カラフルな出力）
174 |             processors.append(
175 |                 structlog.dev.ConsoleRenderer(
176 |                     colors=True,
177 |                 )
178 |             )
179 |         except ImportError:
180 |             # Richが利用できない場合は標準のコンソール出力
181 |             processors.append(structlog.dev.ConsoleRenderer())
182 |     else:
183 |         # Plain text (key=value format)
184 |         processors.append(structlog.processors.KeyValueRenderer())
185 | 
186 |     # structlogの設定
187 |     structlog.configure(
188 |         processors=processors,
189 |         context_class=dict,
190 |         logger_factory=structlog.stdlib.LoggerFactory(),
191 |         wrapper_class=structlog.stdlib.BoundLogger,
192 |         cache_logger_on_first_use=True,
193 |     )
194 | 
195 |     # 標準ライブラリのloggingも設定
196 |     logging.basicConfig(
197 |         format="%(message)s",
198 |         stream=sys.stdout,
199 |         level=getattr(logging, level),
200 |         force=force,
201 |     )
202 | 
203 |     # ファイルハンドラーの追加
204 |     if log_file:
205 |         log_path = Path(log_file)
206 |         log_path.parent.mkdir(parents=True, exist_ok=True)
207 | 
208 |         file_handler = logging.FileHandler(log_path, encoding="utf-8")
209 |         file_handler.setLevel(getattr(logging, level))
210 | 
211 |         # ファイルへの出力は既にstructlogで処理済みなので、そのまま出力
212 |         file_handler.setFormatter(logging.Formatter("%(message)s"))
213 | 
214 |         logging.root.addHandler(file_handler)
215 | 
216 |     # サードパーティライブラリのログレベル調整
217 |     if level != "DEBUG":
218 |         for logger_name in ["urllib3", "asyncio", "filelock"]:
219 |             logging.getLogger(logger_name).setLevel(logging.WARNING)
220 | 
221 | 
222 | def get_logger(name: str, **context: Any) -> BoundLogger:
223 |     """Get a structured logger instance with optional context.
224 | 
225 |     Parameters
226 |     ----------
227 |     name : str
228 |         Name of the logger (typically __name__)
229 |     **context : Any
230 |         Initial context to bind to the logger
231 | 
232 |     Returns
233 |     -------
234 |     BoundLogger
235 |         Configured structlog logger instance
236 | 
237 |     Example
238 |     -------
239 |     >>> logger = get_logger(__name__)
240 |     >>> logger.info("Processing started", items_count=100)
241 | 
242 |     >>> logger = get_logger(__name__, module="data_processor", version="1.0")
243 |     >>> logger.error("Processing failed", error_type="ValidationError")
244 |     """
245 |     logger: BoundLogger = structlog.get_logger(name)
246 | 
247 |     if context:
248 |         logger = logger.bind(**context)
249 | 
250 |     return logger
251 | 
252 | 
253 | @contextmanager
254 | def log_context(**kwargs: Any) -> Iterator[None]:
255 |     """Context manager to temporarily bind context variables.
256 | 
257 |     Parameters
258 |     ----------
259 |     **kwargs : Any
260 |         Context variables to bind
261 | 
262 |     Example
263 |     -------
264 |     >>> logger = get_logger(__name__)
265 |     >>> with log_context(user_id=123, request_id="abc"):
266 |     ...     logger.info("Processing user request")
267 |     ...     # All logs within this context will include user_id and request_id
268 |     """
269 |     bind_contextvars(**kwargs)
270 |     try:
271 |         yield
272 |     finally:
273 |         unbind_contextvars(*kwargs.keys())
274 | 
275 | 
276 | def set_log_level(level: LogLevel | str, logger_name: str | None = None) -> None:
277 |     """Dynamically change the log level.
278 | 
279 |     Parameters
280 |     ----------
281 |     level : LogLevel | str
282 |         New logging level
283 |     logger_name : str | None
284 |         Name of the logger to update. If None, updates root logger
285 |     """
286 |     level_value = getattr(logging, level)
287 | 
288 |     if logger_name:
289 |         logging.getLogger(logger_name).setLevel(level_value)
290 |     else:
291 |         logging.root.setLevel(level_value)
292 |         # Update all handlers
293 |         for handler in logging.root.handlers:
294 |             handler.setLevel(level_value)
295 | 
296 | 
297 | def log_performance(logger: BoundLogger) -> Any:
298 |     """Decorator to log function performance metrics.
299 | 
300 |     Parameters
301 |     ----------
302 |     logger : BoundLogger
303 |         Logger instance to use
304 | 
305 |     Example
306 |     -------
307 |     >>> logger = get_logger(__name__)
308 |     >>> @log_performance(logger)
309 |     ... def process_data(items):
310 |     ...     return [item * 2 for item in items]
311 |     """
312 |     import functools
313 |     import time
314 | 
315 |     def decorator(func: Any) -> Any:
316 |         @functools.wraps(func)
317 |         def wrapper(*args: Any, **kwargs: Any) -> Any:
318 |             start_time = time.perf_counter()
319 |             func_name = func.__name__
320 | 
321 |             # Log function call
322 |             logger.debug(
323 |                 f"Function {func_name} started",
324 |                 function=func_name,
325 |                 args_count=len(args),
326 |                 kwargs_count=len(kwargs),
327 |             )
328 | 
329 |             try:
330 |                 result = func(*args, **kwargs)
331 |                 duration_ms = (time.perf_counter() - start_time) * 1000
332 | 
333 |                 # Log successful completion with duration
334 |                 logger.debug(
335 |                     f"Function {func_name} completed",
336 |                     function=func_name,
337 |                     duration_ms=round(duration_ms, 2),
338 |                     success=True,
339 |                 )
340 | 
341 |                 return result
342 | 
343 |             except Exception as e:
344 |                 duration_ms = (time.perf_counter() - start_time) * 1000
345 | 
346 |                 # Log error with duration
347 |                 logger.error(
348 |                     f"Function {func_name} failed",
349 |                     function=func_name,
350 |                     duration_ms=round(duration_ms, 2),
351 |                     success=False,
352 |                     error_type=type(e).__name__,
353 |                     error_message=str(e),
354 |                     exc_info=True,
355 |                 )
356 |                 raise
357 | 
358 |         return wrapper
359 | 
360 |     return decorator
361 | 


--------------------------------------------------------------------------------
/template/src/template_package/utils/logging_config.py:
--------------------------------------------------------------------------------
  1 | """Structured logging configuration using structlog."""
  2 | 
  3 | import logging
  4 | import os
  5 | import sys
  6 | from collections.abc import Iterator
  7 | from contextlib import contextmanager
  8 | from datetime import UTC, datetime
  9 | from pathlib import Path
 10 | from typing import Any, Protocol
 11 | 
 12 | import structlog
 13 | from structlog import BoundLogger
 14 | from structlog.contextvars import (
 15 |     bind_contextvars,
 16 |     unbind_contextvars,
 17 | )
 18 | 
 19 | from ..types import LogFormat, LogLevel
 20 | 
 21 | 
 22 | class LoggerProtocol(Protocol):
 23 |     """Protocol for structured logger."""
 24 | 
 25 |     def bind(self, **kwargs: Any) -> "LoggerProtocol":
 26 |         """Bind context variables to the logger."""
 27 |         ...
 28 | 
 29 |     def unbind(self, *keys: str) -> "LoggerProtocol":
 30 |         """Unbind context variables from the logger."""
 31 |         ...
 32 | 
 33 |     def debug(self, event: str, **kwargs: Any) -> None:
 34 |         """Log a debug message."""
 35 |         ...
 36 | 
 37 |     def info(self, event: str, **kwargs: Any) -> None:
 38 |         """Log an info message."""
 39 |         ...
 40 | 
 41 |     def warning(self, event: str, **kwargs: Any) -> None:
 42 |         """Log a warning message."""
 43 |         ...
 44 | 
 45 |     def error(self, event: str, **kwargs: Any) -> None:
 46 |         """Log an error message."""
 47 |         ...
 48 | 
 49 |     def critical(self, event: str, **kwargs: Any) -> None:
 50 |         """Log a critical message."""
 51 |         ...
 52 | 
 53 | 
 54 | def add_timestamp(_: Any, __: Any, event_dict: dict[str, Any]) -> dict[str, Any]:
 55 |     """Add ISO timestamp to log entries."""
 56 |     event_dict["timestamp"] = datetime.now(UTC).isoformat()
 57 |     return event_dict
 58 | 
 59 | 
 60 | def add_caller_info(_: Any, __: Any, event_dict: dict[str, Any]) -> dict[str, Any]:
 61 |     """Add caller information (file, function, line) to log entries."""
 62 |     try:
 63 |         # Get the caller frame (skip structlog internals)
 64 |         import inspect
 65 | 
 66 |         frame = None
 67 |         stack = inspect.stack()
 68 | 
 69 |         # Skip the first few frames which are structlog internals
 70 |         for f in stack[4:12]:  # Limit search to avoid infinite loops
 71 |             if f.filename and f.function:
 72 |                 module = inspect.getmodule(f.frame)
 73 |                 if (
 74 |                     module
 75 |                     and not module.__name__.startswith("structlog")
 76 |                     and not module.__name__.startswith("logging")
 77 |                     and "site-packages" not in f.filename
 78 |                 ):
 79 |                     frame = f
 80 |                     break
 81 | 
 82 |         if frame:
 83 |             event_dict["caller"] = {
 84 |                 "filename": Path(frame.filename).name,
 85 |                 "function": frame.function,
 86 |                 "line": frame.lineno,
 87 |             }
 88 |     except Exception:  # nosec B110
 89 |         # If caller info extraction fails, silently continue
 90 |         # This is intentional to prevent logging infrastructure failures
 91 |         pass
 92 | 
 93 |     return event_dict
 94 | 
 95 | 
 96 | def add_log_level_upper(_: Any, __: Any, event_dict: dict[str, Any]) -> dict[str, Any]:
 97 |     """Convert log level to uppercase for consistency."""
 98 |     if "level" in event_dict:
 99 |         event_dict["level"] = event_dict["level"].upper()
100 |     return event_dict
101 | 
102 | 
103 | def setup_logging(
104 |     *,
105 |     level: LogLevel | str = "INFO",
106 |     format: LogFormat = "console",
107 |     log_file: str | Path | None = None,
108 |     include_timestamp: bool = True,
109 |     include_caller_info: bool = True,
110 |     force: bool = False,
111 | ) -> None:
112 |     """Setup structured logging configuration.
113 | 
114 |     Parameters
115 |     ----------
116 |     level : LogLevel | str
117 |         Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
118 |         Can also be set via LOG_LEVEL environment variable
119 |     format : LogFormat
120 |         Output format: "json", "console", or "plain"
121 |         - json: Structured JSON output (best for production)
122 |         - console: Colored, human-readable output (best for development)
123 |         - plain: Simple key=value output
124 |     log_file : str | Path | None
125 |         Optional file path to write logs to
126 |     include_timestamp : bool
127 |         Whether to add ISO timestamps to logs
128 |     include_caller_info : bool
129 |         Whether to add caller information (file, function, line)
130 |     force : bool
131 |         Force reconfiguration even if already configured
132 |     """
133 |     # 環境変数からログレベルを取得
134 |     env_level = os.environ.get("LOG_LEVEL", "").upper()
135 |     if env_level in ["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]:
136 |         level = env_level
137 | 
138 |     # 環境変数からフォーマットを取得
139 |     env_format = os.environ.get("LOG_FORMAT", "").lower()
140 |     if env_format in ["json", "console", "plain"]:
141 |         format = env_format  # type: ignore
142 | 
143 |     # プロセッサの設定
144 |     processors: list[Any] = [
145 |         structlog.contextvars.merge_contextvars,
146 |         structlog.stdlib.filter_by_level,
147 |         structlog.stdlib.add_logger_name,
148 |         structlog.stdlib.add_log_level,
149 |         structlog.stdlib.PositionalArgumentsFormatter(),
150 |         add_log_level_upper,
151 |         structlog.processors.StackInfoRenderer(),
152 |         structlog.processors.format_exc_info,
153 |     ]
154 | 
155 |     # Add timestamp processor if enabled
156 |     if include_timestamp:
157 |         processors.insert(3, add_timestamp)
158 | 
159 |     # Add caller info processor if enabled
160 |     if include_caller_info:
161 |         processors.insert(4, add_caller_info)
162 | 
163 |     # 開発環境判定
164 |     is_development = (
165 |         os.environ.get("PROJECT_ENV") == "development" or format == "console"
166 |     )
167 | 
168 |     # レンダラーの選択
169 |     if format == "json":
170 |         processors.append(structlog.processors.JSONRenderer())
171 |     elif format == "console" and is_development:
172 |         try:
173 |             # Rich ConsoleRendererを使用（カラフルな出力）
174 |             processors.append(
175 |                 structlog.dev.ConsoleRenderer(
176 |                     colors=True,
177 |                 )
178 |             )
179 |         except ImportError:
180 |             # Richが利用できない場合は標準のコンソール出力
181 |             processors.append(structlog.dev.ConsoleRenderer())
182 |     else:
183 |         # Plain text (key=value format)
184 |         processors.append(structlog.processors.KeyValueRenderer())
185 | 
186 |     # structlogの設定
187 |     structlog.configure(
188 |         processors=processors,
189 |         context_class=dict,
190 |         logger_factory=structlog.stdlib.LoggerFactory(),
191 |         wrapper_class=structlog.stdlib.BoundLogger,
192 |         cache_logger_on_first_use=True,
193 |     )
194 | 
195 |     # 標準ライブラリのloggingも設定
196 |     logging.basicConfig(
197 |         format="%(message)s",
198 |         stream=sys.stdout,
199 |         level=getattr(logging, level.upper()),
200 |         force=force,
201 |     )
202 | 
203 |     # ファイルハンドラーの追加
204 |     if log_file:
205 |         log_path = Path(log_file)
206 |         log_path.parent.mkdir(parents=True, exist_ok=True)
207 | 
208 |         file_handler = logging.FileHandler(log_path, encoding="utf-8")
209 |         file_handler.setLevel(getattr(logging, level.upper()))
210 | 
211 |         # ファイルへの出力は既にstructlogで処理済みなので、そのまま出力
212 |         file_handler.setFormatter(logging.Formatter("%(message)s"))
213 | 
214 |         logging.root.addHandler(file_handler)
215 | 
216 |     # サードパーティライブラリのログレベル調整
217 |     if level != "DEBUG":
218 |         for logger_name in ["urllib3", "asyncio", "filelock"]:
219 |             logging.getLogger(logger_name).setLevel(logging.WARNING)
220 | 
221 | 
222 | def get_logger(name: str, **context: Any) -> BoundLogger:
223 |     """Get a structured logger instance with optional context.
224 | 
225 |     Parameters
226 |     ----------
227 |     name : str
228 |         Name of the logger (typically __name__)
229 |     **context : Any
230 |         Initial context to bind to the logger
231 | 
232 |     Returns
233 |     -------
234 |     BoundLogger
235 |         Configured structlog logger instance
236 | 
237 |     Example
238 |     -------
239 |     >>> logger = get_logger(__name__)
240 |     >>> logger.info("Processing started", items_count=100)
241 | 
242 |     >>> logger = get_logger(__name__, module="data_processor", version="1.0")
243 |     >>> logger.error("Processing failed", error_type="ValidationError")
244 |     """
245 |     logger: BoundLogger = structlog.get_logger(name)
246 | 
247 |     if context:
248 |         logger = logger.bind(**context)
249 | 
250 |     return logger
251 | 
252 | 
253 | @contextmanager
254 | def log_context(**kwargs: Any) -> Iterator[None]:
255 |     """Context manager to temporarily bind context variables.
256 | 
257 |     Parameters
258 |     ----------
259 |     **kwargs : Any
260 |         Context variables to bind
261 | 
262 |     Example
263 |     -------
264 |     >>> logger = get_logger(__name__)
265 |     >>> with log_context(user_id=123, request_id="abc"):
266 |     ...     logger.info("Processing user request")
267 |     ...     # All logs within this context will include user_id and request_id
268 |     """
269 |     bind_contextvars(**kwargs)
270 |     try:
271 |         yield
272 |     finally:
273 |         unbind_contextvars(*kwargs.keys())
274 | 
275 | 
276 | def set_log_level(level: LogLevel | str, logger_name: str | None = None) -> None:
277 |     """Dynamically change the log level.
278 | 
279 |     Parameters
280 |     ----------
281 |     level : LogLevel | str
282 |         New logging level
283 |     logger_name : str | None
284 |         Name of the logger to update. If None, updates root logger
285 |     """
286 |     level_value = getattr(logging, level.upper())
287 | 
288 |     if logger_name:
289 |         logging.getLogger(logger_name).setLevel(level_value)
290 |     else:
291 |         logging.root.setLevel(level_value)
292 |         # Update all handlers
293 |         for handler in logging.root.handlers:
294 |             handler.setLevel(level_value)
295 | 
296 | 
297 | def log_performance(logger: BoundLogger) -> Any:
298 |     """Decorator to log function performance metrics.
299 | 
300 |     Parameters
301 |     ----------
302 |     logger : BoundLogger
303 |         Logger instance to use
304 | 
305 |     Example
306 |     -------
307 |     >>> logger = get_logger(__name__)
308 |     >>> @log_performance(logger)
309 |     ... def process_data(items):
310 |     ...     return [item * 2 for item in items]
311 |     """
312 |     import functools
313 |     import time
314 | 
315 |     def decorator(func: Any) -> Any:
316 |         @functools.wraps(func)
317 |         def wrapper(*args: Any, **kwargs: Any) -> Any:
318 |             start_time = time.perf_counter()
319 |             func_name = func.__name__
320 | 
321 |             # Log function call
322 |             logger.debug(
323 |                 f"Function {func_name} started",
324 |                 function=func_name,
325 |                 args_count=len(args),
326 |                 kwargs_count=len(kwargs),
327 |             )
328 | 
329 |             try:
330 |                 result = func(*args, **kwargs)
331 |                 duration_ms = (time.perf_counter() - start_time) * 1000
332 | 
333 |                 # Log successful completion with duration
334 |                 logger.debug(
335 |                     f"Function {func_name} completed",
336 |                     function=func_name,
337 |                     duration_ms=round(duration_ms, 2),
338 |                     success=True,
339 |                 )
340 | 
341 |                 return result
342 | 
343 |             except Exception as e:
344 |                 duration_ms = (time.perf_counter() - start_time) * 1000
345 | 
346 |                 # Log error with duration
347 |                 logger.error(
348 |                     f"Function {func_name} failed",
349 |                     function=func_name,
350 |                     duration_ms=round(duration_ms, 2),
351 |                     success=False,
352 |                     error_type=type(e).__name__,
353 |                     error_message=str(e),
354 |                     exc_info=True,
355 |                 )
356 |                 raise
357 | 
358 |         return wrapper
359 | 
360 |     return decorator
361 | 


--------------------------------------------------------------------------------
/template/src/template_package/utils/profiling.py:
--------------------------------------------------------------------------------
  1 | """Performance profiling utilities."""
  2 | 
  3 | import cProfile
  4 | import functools
  5 | import io
  6 | import pstats
  7 | import time
  8 | from collections.abc import Callable, Iterator
  9 | from contextlib import contextmanager
 10 | from pathlib import Path
 11 | from typing import Any, ParamSpec, TypeVar, overload
 12 | 
 13 | P = ParamSpec("P")
 14 | R = TypeVar("R")
 15 | 
 16 | 
 17 | class ProfileResult:
 18 |     """Container for profiling results."""
 19 | 
 20 |     def __init__(
 21 |         self,
 22 |         elapsed_time: float,
 23 |         stats: pstats.Stats | None = None,
 24 |     ) -> None:
 25 |         """Initialize ProfileResult.
 26 | 
 27 |         Parameters
 28 |         ----------
 29 |         elapsed_time : float
 30 |             Elapsed time in seconds
 31 |         stats : pstats.Stats | None
 32 |             cProfile statistics object
 33 |         """
 34 |         self.elapsed_time = elapsed_time
 35 |         self.stats = stats
 36 | 
 37 |     def print_stats(
 38 |         self,
 39 |         *,
 40 |         sort_by: str = "cumulative",
 41 |         limit: int = 20,
 42 |     ) -> None:
 43 |         """Print profiling statistics.
 44 | 
 45 |         Parameters
 46 |         ----------
 47 |         sort_by : str
 48 |             Sort criteria for stats (cumulative, time, calls, etc.)
 49 |         limit : int
 50 |             Number of top functions to show
 51 |         """
 52 |         if self.stats:
 53 |             print(f"\nTotal elapsed time: {self.elapsed_time:.4f} seconds")
 54 |             self.stats.sort_stats(sort_by).print_stats(limit)
 55 |         else:
 56 |             print(f"Elapsed time: {self.elapsed_time:.4f} seconds")
 57 | 
 58 |     def save_stats(self, filepath: str | Path) -> None:
 59 |         """Save profiling statistics to file.
 60 | 
 61 |         Parameters
 62 |         ----------
 63 |         filepath : str | Path
 64 |             Path to save the stats file
 65 |         """
 66 |         if self.stats:
 67 |             self.stats.dump_stats(str(filepath))
 68 | 
 69 | 
 70 | @contextmanager
 71 | def profile_context(
 72 |     *,
 73 |     enabled: bool = True,
 74 |     print_stats: bool = True,
 75 |     sort_by: str = "cumulative",
 76 |     limit: int = 20,
 77 | ) -> Iterator[ProfileResult]:
 78 |     """Context manager for profiling code blocks.
 79 | 
 80 |     Parameters
 81 |     ----------
 82 |     enabled : bool
 83 |         Whether profiling is enabled
 84 |     print_stats : bool
 85 |         Whether to print stats after profiling
 86 |     sort_by : str
 87 |         Sort criteria for stats
 88 |     limit : int
 89 |         Number of top functions to show
 90 | 
 91 |     Yields
 92 |     ------
 93 |     ProfileResult
 94 |         Profiling results object
 95 | 
 96 |     Examples
 97 |     --------
 98 |     >>> with profile_context() as prof:
 99 |     ...     # Code to profile
100 |     ...     time.sleep(0.1)
101 |     >>> print(f"Took {prof.elapsed_time:.2f} seconds")
102 |     """
103 |     if not enabled:
104 |         start_time = time.perf_counter()
105 |         result = ProfileResult(0)
106 |         yield result
107 |         result.elapsed_time = time.perf_counter() - start_time
108 |         return
109 | 
110 |     profiler = cProfile.Profile()
111 |     start_time = time.perf_counter()
112 | 
113 |     profiler.enable()
114 |     result = ProfileResult(0)
115 | 
116 |     try:
117 |         yield result
118 |     finally:
119 |         profiler.disable()
120 |         elapsed_time = time.perf_counter() - start_time
121 | 
122 |         # Create stats
123 |         s = io.StringIO()
124 |         stats = pstats.Stats(profiler, stream=s)
125 | 
126 |         result.elapsed_time = elapsed_time
127 |         result.stats = stats
128 | 
129 |         if print_stats:
130 |             result.print_stats(sort_by=sort_by, limit=limit)
131 | 
132 | 
133 | @overload
134 | def profile(
135 |     func: Callable[P, R],
136 | ) -> Callable[P, R]:
137 |     """Profile a function (when used without arguments)."""
138 |     ...
139 | 
140 | 
141 | @overload
142 | def profile(
143 |     *,
144 |     enabled: bool = True,
145 |     print_stats: bool = True,
146 |     sort_by: str = "cumulative",
147 |     limit: int = 20,
148 | ) -> Callable[[Callable[P, R]], Callable[P, R]]:
149 |     """Profile a function with options."""
150 |     ...
151 | 
152 | 
153 | def profile(
154 |     func: Callable[P, R] | None = None,
155 |     *,
156 |     enabled: bool = True,
157 |     print_stats: bool = True,
158 |     sort_by: str = "cumulative",
159 |     limit: int = 20,
160 | ) -> Callable[P, R] | Callable[[Callable[P, R]], Callable[P, R]]:
161 |     """Decorator for profiling functions.
162 | 
163 |     Parameters
164 |     ----------
165 |     func : Callable | None
166 |         Function to profile (when used without parentheses)
167 |     enabled : bool
168 |         Whether profiling is enabled
169 |     print_stats : bool
170 |         Whether to print stats after each call
171 |     sort_by : str
172 |         Sort criteria for stats
173 |     limit : int
174 |         Number of top functions to show
175 | 
176 |     Returns
177 |     -------
178 |     Callable
179 |         Decorated function
180 | 
181 |     Examples
182 |     --------
183 |     >>> @profile
184 |     ... def slow_function():
185 |     ...     time.sleep(0.1)
186 |     ...     return 42
187 | 
188 |     >>> @profile(enabled=False)
189 |     ... def fast_function():
190 |     ...     return 1 + 1
191 | 
192 |     >>> @profile(sort_by="time", limit=10)
193 |     ... def complex_function():
194 |     ...     # Complex logic here
195 |     ...     pass
196 |     """
197 | 
198 |     def decorator(f: Callable[P, R]) -> Callable[P, R]:
199 |         @functools.wraps(f)
200 |         def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
201 |             if not enabled:
202 |                 return f(*args, **kwargs)
203 | 
204 |             with profile_context(
205 |                 enabled=True,
206 |                 print_stats=print_stats,
207 |                 sort_by=sort_by,
208 |                 limit=limit,
209 |             ):
210 |                 result = f(*args, **kwargs)
211 | 
212 |             # Add function name to output
213 |             if print_stats:
214 |                 print(f"\nProfile for {f.__name__}")
215 | 
216 |             return result
217 | 
218 |         # Add attribute to access profiling on/off
219 |         wrapper.profiling_enabled = enabled  # type: ignore[attr-defined]
220 | 
221 |         return wrapper
222 | 
223 |     if func is None:
224 |         return decorator
225 |     else:
226 |         return decorator(func)
227 | 
228 | 
229 | def timeit(
230 |     func: Callable[P, R] | None = None,
231 |     *,
232 |     enabled: bool = True,
233 |     print_time: bool = True,
234 |     precision: int = 4,
235 | ) -> Callable[P, R] | Callable[[Callable[P, R]], Callable[P, R]]:
236 |     """Simple timing decorator.
237 | 
238 |     Parameters
239 |     ----------
240 |     func : Callable | None
241 |         Function to time
242 |     enabled : bool
243 |         Whether timing is enabled
244 |     print_time : bool
245 |         Whether to print timing after each call
246 |     precision : int
247 |         Decimal precision for time display
248 | 
249 |     Returns
250 |     -------
251 |     Callable
252 |         Decorated function
253 | 
254 |     Examples
255 |     --------
256 |     >>> @timeit
257 |     ... def some_function():
258 |     ...     time.sleep(0.1)
259 | 
260 |     >>> @timeit(precision=6)
261 |     ... def precise_function():
262 |     ...     return sum(range(1000))
263 |     """
264 | 
265 |     def decorator(f: Callable[P, R]) -> Callable[P, R]:
266 |         @functools.wraps(f)
267 |         def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
268 |             if not enabled:
269 |                 return f(*args, **kwargs)
270 | 
271 |             start = time.perf_counter()
272 |             result = f(*args, **kwargs)
273 |             elapsed = time.perf_counter() - start
274 | 
275 |             if print_time:
276 |                 print(f"{f.__name__} took {elapsed:.{precision}f} seconds")
277 | 
278 |             return result
279 | 
280 |         wrapper.timing_enabled = enabled  # type: ignore[attr-defined]
281 |         return wrapper
282 | 
283 |     if func is None:
284 |         return decorator
285 |     else:
286 |         return decorator(func)
287 | 
288 | 
289 | class Timer:
290 |     """Simple timer class for measuring elapsed time.
291 | 
292 |     Examples
293 |     --------
294 |     >>> timer = Timer()
295 |     >>> timer.start()
296 |     >>> # Do some work
297 |     >>> elapsed = timer.stop()
298 |     >>> print(f"Elapsed: {elapsed:.2f} seconds")
299 | 
300 |     >>> # Use as context manager
301 |     >>> with Timer() as timer:
302 |     ...     # Do some work
303 |     ...     pass
304 |     >>> print(f"Elapsed: {timer.elapsed:.2f} seconds")
305 |     """
306 | 
307 |     def __init__(self, *, name: str | None = None) -> None:
308 |         """Initialize Timer.
309 | 
310 |         Parameters
311 |         ----------
312 |         name : str | None
313 |             Optional name for the timer
314 |         """
315 |         self.name = name
316 |         self._start_time: float | None = None
317 |         self._elapsed: float = 0.0
318 | 
319 |     def start(self) -> None:
320 |         """Start the timer."""
321 |         self._start_time = time.perf_counter()
322 | 
323 |     def stop(self) -> float:
324 |         """Stop the timer and return elapsed time.
325 | 
326 |         Returns
327 |         -------
328 |         float
329 |             Elapsed time in seconds
330 | 
331 |         Raises
332 |         ------
333 |         RuntimeError
334 |             If timer was not started
335 |         """
336 |         if self._start_time is None:
337 |             raise RuntimeError("Timer not started")
338 | 
339 |         self._elapsed = time.perf_counter() - self._start_time
340 |         self._start_time = None
341 |         return self._elapsed
342 | 
343 |     @property
344 |     def elapsed(self) -> float:
345 |         """Get elapsed time.
346 | 
347 |         Returns
348 |         -------
349 |         float
350 |             Elapsed time in seconds
351 |         """
352 |         if self._start_time is not None:
353 |             # Timer is still running
354 |             return time.perf_counter() - self._start_time
355 |         return self._elapsed
356 | 
357 |     def __enter__(self) -> "Timer":
358 |         """Enter context manager."""
359 |         self.start()
360 |         return self
361 | 
362 |     def __exit__(self, *args: Any) -> None:
363 |         """Exit context manager."""
364 |         self.stop()
365 |         if self.name:
366 |             print(f"{self.name}: {self._elapsed:.4f} seconds")
367 | 
368 | 
369 | def compare_performance(
370 |     functions: dict[str, Callable[[], Any]],
371 |     *,
372 |     iterations: int = 1,
373 |     warmup: int = 0,
374 | ) -> dict[str, float]:
375 |     """Compare performance of multiple functions.
376 | 
377 |     Parameters
378 |     ----------
379 |     functions : dict[str, Callable]
380 |         Dictionary of function names to functions
381 |     iterations : int
382 |         Number of iterations to run each function
383 |     warmup : int
384 |         Number of warmup iterations before timing
385 | 
386 |     Returns
387 |     -------
388 |     dict[str, float]
389 |         Dictionary of function names to average execution times
390 | 
391 |     Examples
392 |     --------
393 |     >>> def approach1():
394 |     ...     return sum(range(1000))
395 |     ...
396 |     >>> def approach2():
397 |     ...     return sum(x for x in range(1000))
398 |     ...
399 |     >>> results = compare_performance({
400 |     ...     "list": approach1,
401 |     ...     "generator": approach2,
402 |     ... }, iterations=1000)
403 |     """
404 |     results: dict[str, float] = {}
405 | 
406 |     for name, func in functions.items():
407 |         # Warmup runs
408 |         for _ in range(warmup):
409 |             func()
410 | 
411 |         # Timed runs
412 |         times: list[float] = []
413 |         for _ in range(iterations):
414 |             start = time.perf_counter()
415 |             func()
416 |             elapsed = time.perf_counter() - start
417 |             times.append(elapsed)
418 | 
419 |         avg_time = sum(times) / len(times)
420 |         results[name] = avg_time
421 | 
422 |     # Print comparison
423 |     if results:
424 |         baseline_name = next(iter(results))
425 |         baseline_time = results[baseline_name]
426 | 
427 |         print("\nPerformance Comparison:")
428 |         print("-" * 50)
429 |         for name, avg_time in sorted(results.items(), key=lambda x: x[1]):
430 |             ratio = avg_time / baseline_time
431 |             print(f"{name:20} {avg_time * 1000:10.4f} ms ({ratio:6.2f}x)")
432 | 
433 |     return results
434 | 


--------------------------------------------------------------------------------
/template/tests/integration/test_example.py:
--------------------------------------------------------------------------------
  1 | """Integration tests for template_package components.
  2 | 
  3 | This module demonstrates how to write integration tests that verify
  4 | the interaction between multiple components of the template_package.
  5 | """
  6 | 
  7 | from pathlib import Path
  8 | 
  9 | import pytest
 10 | from template_package.core.example import ExampleClass, ExampleConfig, process_data
 11 | from template_package.types import ItemDict
 12 | from template_package.utils.helpers import chunk_list, load_json_file, save_json_file
 13 | from template_package.utils.logging_config import get_logger
 14 | 
 15 | # モジュールレベルのロガー
 16 | logger = get_logger(__name__)
 17 | 
 18 | 
 19 | class SimpleDataProcessor:
 20 |     """Simple data processor for testing integration."""
 21 | 
 22 |     def process(self, data: list[ItemDict]) -> list[ItemDict]:
 23 |         """Process data by adding a processed flag and incrementing values."""
 24 |         logger.debug(f"Processing {len(data)} items with SimpleDataProcessor")
 25 | 
 26 |         processed_data = []
 27 |         for item in data:
 28 |             processed_item = item.copy()
 29 |             processed_item["value"] = item["value"] * 2  # Double the value
 30 |             processed_item["processed"] = True  # Add processed flag
 31 |             processed_data.append(processed_item)
 32 | 
 33 |         logger.debug(f"Processed {len(processed_data)} items successfully")
 34 |         return processed_data
 35 | 
 36 | 
 37 | class TestExampleClassIntegration:
 38 |     """Integration tests for ExampleClass with other components."""
 39 | 
 40 |     def test_正常系_ExampleClassとヘルパー関数の連携(self, temp_dir: Path) -> None:
 41 |         """ExampleClassとヘルパー関数が正しく連携することを確認。"""
 42 |         logger.debug("Starting ExampleClass and helper function integration test")
 43 | 
 44 |         # 1. 設定ファイルをJSONで作成
 45 |         config_data = {
 46 |             "name": "integration_test",
 47 |             "max_items": 5,
 48 |             "enable_validation": True,
 49 |         }
 50 |         config_file = temp_dir / "config.json"
 51 |         save_json_file(config_data, config_file)
 52 | 
 53 |         # 2. 設定ファイルを読み込んでExampleClassを初期化
 54 |         loaded_config_data = load_json_file(config_file)
 55 |         config = ExampleConfig(
 56 |             name=loaded_config_data["name"],
 57 |             max_items=loaded_config_data["max_items"],
 58 |             enable_validation=loaded_config_data["enable_validation"],
 59 |         )
 60 |         example = ExampleClass(config)
 61 | 
 62 |         # 3. テストデータを準備してアイテムを追加
 63 |         test_items = [
 64 |             {"id": 1, "name": "Item 1", "value": 10},
 65 |             {"id": 2, "name": "Item 2", "value": 20},
 66 |             {"id": 3, "name": "Item 3", "value": 30},
 67 |         ]
 68 | 
 69 |         for item in test_items:
 70 |             example.add_item(item)
 71 | 
 72 |         # 4. データを取得してチャンク化
 73 |         all_items = example.get_items()
 74 |         chunks = chunk_list(all_items, chunk_size=2)
 75 | 
 76 |         # 5. 検証
 77 |         assert len(all_items) == 3
 78 |         assert len(chunks) == 2  # [2, 1]に分割される
 79 |         assert len(chunks[0]) == 2
 80 |         assert len(chunks[1]) == 1
 81 | 
 82 |         logger.info(
 83 |             "ExampleClass and helper function integration test completed successfully"
 84 |         )
 85 | 
 86 |     def test_正常系_データ処理パイプラインの統合(self, temp_dir: Path) -> None:
 87 |         """データ処理パイプライン全体の統合テスト。"""
 88 |         logger.debug("Starting data processing pipeline integration test")
 89 | 
 90 |         # 1. 入力データファイルを作成
 91 |         input_data = [
 92 |             {"id": 1, "name": "Data 1", "value": 5},
 93 |             {"id": 2, "name": "Data 2", "value": 10},
 94 |             {"id": 3, "name": "Data 3", "value": 15},
 95 |         ]
 96 |         input_file = temp_dir / "input.json"
 97 |         save_json_file({"items": input_data}, input_file)
 98 | 
 99 |         # 2. データファイルを読み込み
100 |         file_data = load_json_file(input_file)
101 |         items_data = file_data["items"]
102 | 
103 |         # 3. ExampleClassでデータ管理
104 |         config = ExampleConfig(name="pipeline_test", max_items=10)
105 |         example = ExampleClass(config)
106 | 
107 |         for item in items_data:
108 |             example.add_item(item)
109 | 
110 |         # 4. データ処理
111 |         processor = SimpleDataProcessor()
112 |         raw_data = example.get_items()
113 |         processed_data = process_data(raw_data, processor)
114 | 
115 |         # 5. 結果をファイルに保存
116 |         output_file = temp_dir / "output.json"
117 |         save_json_file({"processed_items": processed_data}, output_file)
118 | 
119 |         # 6. 保存されたファイルを読み込んで検証
120 |         result_data = load_json_file(output_file)
121 |         result_items = result_data["processed_items"]
122 | 
123 |         # 検証
124 |         assert len(result_items) == 3
125 |         for i, item in enumerate(result_items):
126 |             expected_value = input_data[i]["value"] * 2
127 |             assert item["value"] == expected_value
128 |             assert item["processed"] is True
129 |             assert item["id"] == input_data[i]["id"]
130 |             assert item["name"] == input_data[i]["name"]
131 | 
132 |         logger.info("Data processing pipeline integration test completed successfully")
133 | 
134 |     def test_正常系_エラーハンドリングとリカバリー(self, temp_dir: Path) -> None:
135 |         """エラーハンドリングとリカバリーの統合テスト。"""
136 |         logger.debug("Starting error handling and recovery integration test")
137 | 
138 |         # 1. 不正なデータを含むファイルを作成
139 |         mixed_data = [
140 |             {"id": 1, "name": "Valid Item", "value": 100},  # 正常データ
141 |             {"id": 2, "name": "", "value": 200},  # name が空（バリデーションエラー）
142 |             {"id": 3, "name": "Another Valid", "value": 300},  # 正常データ
143 |         ]
144 | 
145 |         config = ExampleConfig(name="error_test", max_items=5, enable_validation=True)
146 |         example = ExampleClass(config)
147 | 
148 |         # 2. データを追加（エラーハンドリング）
149 |         successful_items = []
150 |         failed_items = []
151 | 
152 |         for item in mixed_data:
153 |             try:
154 |                 example.add_item(item)
155 |                 successful_items.append(item)
156 |                 logger.debug(f"Successfully added item: {item['id']}")
157 |             except ValueError as e:
158 |                 failed_items.append(item)
159 |                 logger.warning(f"Failed to add item {item['id']}: {e}")
160 | 
161 |         # 3. 成功したデータのみを処理
162 |         if successful_items:
163 |             valid_data = example.get_items()
164 |             processor = SimpleDataProcessor()
165 |             processed_data = process_data(valid_data, processor)
166 | 
167 |             # 結果を保存
168 |             output_file = temp_dir / "recovered_output.json"
169 |             save_json_file(
170 |                 {
171 |                     "processed_items": processed_data,
172 |                     "failed_items": failed_items,
173 |                     "summary": {
174 |                         "total_input": len(mixed_data),
175 |                         "successful": len(successful_items),
176 |                         "failed": len(failed_items),
177 |                     },
178 |                 },
179 |                 output_file,
180 |             )
181 | 
182 |             # 検証
183 |             result = load_json_file(output_file)
184 |             assert len(result["processed_items"]) == 2  # 正常データのみ
185 |             assert len(result["failed_items"]) == 1  # エラーデータ
186 |             assert result["summary"]["total_input"] == 3
187 |             assert result["summary"]["successful"] == 2
188 |             assert result["summary"]["failed"] == 1
189 | 
190 |             logger.info(
191 |                 "Error handling and recovery integration test completed successfully"
192 |             )
193 | 
194 |     def test_正常系_大量データ処理のパフォーマンス(self, temp_dir: Path) -> None:
195 |         """大量データ処理時のパフォーマンステスト。"""
196 |         logger.debug("Starting large data processing performance test")
197 | 
198 |         # 1. 大量のテストデータを生成
199 |         large_dataset = [
200 |             {"id": i, "name": f"Item {i}", "value": i * 10}
201 |             for i in range(1, 1001)  # 1000件のデータ
202 |         ]
203 | 
204 |         # 2. ExampleClassで大量データを管理
205 |         config = ExampleConfig(name="performance_test", max_items=1500)
206 |         example = ExampleClass(config)
207 | 
208 |         # データをバッチで追加
209 |         batch_size = 100
210 |         batches = chunk_list(large_dataset, batch_size)
211 | 
212 |         for batch_num, batch in enumerate(batches):
213 |             logger.debug(f"Processing batch {batch_num + 1}/{len(batches)}")
214 |             for item in batch:
215 |                 example.add_item(item)
216 | 
217 |         # 3. 全データを取得して処理
218 |         all_data = example.get_items()
219 |         processor = SimpleDataProcessor()
220 |         processed_data = process_data(all_data, processor)
221 | 
222 |         # 4. 結果をチャンク化して保存
223 |         output_chunks = chunk_list(processed_data, 200)
224 | 
225 |         chunk_files = []
226 |         for i, chunk in enumerate(output_chunks):
227 |             chunk_file = temp_dir / f"output_chunk_{i}.json"
228 |             save_json_file({"chunk": i, "data": chunk}, chunk_file)
229 |             chunk_files.append(chunk_file)
230 | 
231 |         # 5. 検証
232 |         assert len(all_data) == 1000
233 |         assert len(processed_data) == 1000
234 |         assert len(output_chunks) == 5  # 1000 / 200 = 5チャンク
235 | 
236 |         # 各チャンクファイルの検証
237 |         total_verified = 0
238 |         for chunk_file in chunk_files:
239 |             chunk_data = load_json_file(chunk_file)
240 |             total_verified += len(chunk_data["data"])
241 | 
242 |         assert total_verified == 1000
243 | 
244 |         logger.info(
245 |             f"Large data processing test completed: {total_verified} items processed"
246 |         )
247 | 
248 |     def test_異常系_連鎖エラーハンドリング(self, temp_dir: Path) -> None:
249 |         """複数コンポーネント間でのエラーの連鎖処理テスト。"""
250 |         logger.debug("Starting cascade error handling test")
251 | 
252 |         # 1. 存在しないファイルの読み込みエラー
253 |         nonexistent_file = temp_dir / "nonexistent.json"
254 | 
255 |         with pytest.raises(FileNotFoundError):
256 |             load_json_file(nonexistent_file)
257 | 
258 |         # 2. 不正なJSONファイルの処理
259 |         invalid_json_file = temp_dir / "invalid.json"
260 |         invalid_json_file.write_text("{ invalid json content", encoding="utf-8")
261 | 
262 |         with pytest.raises(ValueError, match="Invalid JSON"):
263 |             load_json_file(invalid_json_file)
264 | 
265 |         # 3. 容量制限エラーの処理
266 |         config = ExampleConfig(name="limit_test", max_items=2)
267 |         example = ExampleClass(config)
268 | 
269 |         # 制限を超えるデータ追加
270 |         items = [
271 |             {"id": 1, "name": "Item 1", "value": 10},
272 |             {"id": 2, "name": "Item 2", "value": 20},
273 |             {"id": 3, "name": "Item 3", "value": 30},  # これでエラーになる
274 |         ]
275 | 
276 |         # 最初の2つは成功
277 |         example.add_item(items[0])
278 |         example.add_item(items[1])
279 | 
280 |         # 3つ目でエラー
281 |         with pytest.raises(ValueError, match="max_items limit"):
282 |             example.add_item(items[2])
283 | 
284 |         # 現在のデータは2件のまま
285 |         assert len(example) == 2
286 | 
287 |         logger.info("Cascade error handling test completed successfully")
288 | 
289 | 
290 | class TestMultiComponentIntegration:
291 |     """複数コンポーネントの統合テスト。"""
292 | 
293 |     def test_正常系_ファイルIO_データ処理_チャンク化の統合(
294 |         self, temp_dir: Path
295 |     ) -> None:
296 |         """ファイルIO、データ処理、チャンク化の完全な統合テスト。"""
297 |         logger.debug("Starting comprehensive integration test")
298 | 
299 |         # 1. 複数のデータファイルを作成
300 |         datasets = {
301 |             "users": [
302 |                 {"id": 1, "name": "Alice", "value": 100},
303 |                 {"id": 2, "name": "Bob", "value": 150},
304 |             ],
305 |             "products": [
306 |                 {"id": 3, "name": "Product A", "value": 200},
307 |                 {"id": 4, "name": "Product B", "value": 250},
308 |                 {"id": 5, "name": "Product C", "value": 300},
309 |             ],
310 |         }
311 | 
312 |         data_files = {}
313 |         for category, data in datasets.items():
314 |             file_path = temp_dir / f"{category}.json"
315 |             save_json_file({"items": data}, file_path)
316 |             data_files[category] = file_path
317 | 
318 |         # 2. 各ファイルからデータを読み込み、統合
319 |         all_items = []
320 |         for category, file_path in data_files.items():
321 |             file_data = load_json_file(file_path)
322 |             items = file_data["items"]
323 |             logger.debug(f"Loaded {len(items)} items from {category}")
324 |             all_items.extend(items)
325 | 
326 |         # 3. ExampleClassで統合データを管理
327 |         config = ExampleConfig(name="multi_component_test", max_items=10)
328 |         example = ExampleClass(config)
329 | 
330 |         for item in all_items:
331 |             example.add_item(item)
332 | 
333 |         # 4. データを処理
334 |         processor = SimpleDataProcessor()
335 |         managed_data = example.get_items()
336 |         processed_data = process_data(managed_data, processor)
337 | 
338 |         # 5. 結果をカテゴリ別にチャンク化
339 |         user_results = [item for item in processed_data if item["id"] <= 2]
340 |         product_results = [item for item in processed_data if item["id"] > 2]
341 | 
342 |         # 6. チャンク化して保存
343 |         user_chunks = chunk_list(user_results, 1)  # 1つずつ分割
344 |         product_chunks = chunk_list(product_results, 2)  # 2つずつ分割
345 | 
346 |         # 結果を保存
347 |         results_file = temp_dir / "integration_results.json"
348 |         save_json_file(
349 |             {
350 |                 "user_chunks": len(user_chunks),
351 |                 "product_chunks": len(product_chunks),
352 |                 "total_processed": len(processed_data),
353 |                 "user_results": user_results,
354 |                 "product_results": product_results,
355 |             },
356 |             results_file,
357 |         )
358 | 
359 |         # 7. 検証
360 |         results = load_json_file(results_file)
361 | 
362 |         assert results["total_processed"] == 5
363 |         assert results["user_chunks"] == 2  # 2ユーザー、1つずつ
364 |         assert results["product_chunks"] == 2  # 3商品、2つずつで2チャンク
365 |         assert len(results["user_results"]) == 2
366 |         assert len(results["product_results"]) == 3
367 | 
368 |         # 処理結果の値が正しく倍になっているか確認
369 |         for result in results["user_results"]:
370 |             original_value = next(
371 |                 item["value"]
372 |                 for dataset in datasets.values()
373 |                 for item in dataset
374 |                 if item["id"] == result["id"]
375 |             )
376 |             assert result["value"] == original_value * 2
377 |             assert result["processed"] is True
378 | 
379 |         logger.info(
380 |             "Comprehensive multi-component integration test completed successfully"
381 |         )
382 | 


--------------------------------------------------------------------------------