CR-NEXUS-047: Completion Report 解析ロジックのテストヘルパー共通化 - 完了レポート

実装日時

2025年12月25日

概要

目的

tests/api/test_completion_report_content_quality_gate.py 等で使っている「Completion Report のセクション抽出・空判定・証跡検出」ロジックをテスト専用ヘルパーに切り出し、今後の品質ゲート拡張に備える。挙動は一切変更しない（リファクタのみ）。

背景

  • README 解析は tests/api/_readme_cr_helpers.py に共通化されている（CR-NEXUS-043/045/046）
  • Completion Report 側は品質ゲートが増えており（CR-NEXUS-042/044）、今後も同様の抽出ロジックが増える見込み
  • 解析ロジックが各テスト内に散らばると、保守コストと不整合リスクが上がる

ゴール

  • Completion Report 解析ロジックを tests/api/_completion_report_helpers.py に共通化
  • 既存テストの期待値は変更しない（リファクタのみ）
  • 既存の品質ゲート仕様（判定ルール）は変えない

実装ステップ

Step 1: 新規ヘルパーファイルの作成

実施内容:

  • tests/api/_completion_report_helpers.py を新規作成
  • 以下の関数を実装：
    • extract_section_content(): Completion Report から指定セクションの内容を抽出（サブセクション ### を含む）
    • is_effectively_empty_text(): 空行のみ / Markdown 記号のみ / 既知プレースホルダのみ を「実質空」と判定
    • contains_step_markers(): “Step 1” 等の Step パターン検出
    • contains_file_paths(): src/..., tests/..., docs/... 等の「それっぽいパス」検出
    • contains_evidence(): 実行コマンド/結果記述の検出

実装詳細:

  • 既存テストの抽出実装をそのままヘルパーへ移植し、正規表現・境界条件を変えない
  • README 解析は _readme_cr_helpers.py、Report 解析は _completion_report_helpers.py に固定し、相互 import を禁止

Step 2: 既存テストのリファクタ

実施内容:

  • tests/api/test_completion_report_content_quality_gate.py のロジックを上記ヘルパーに移動
  • テストはヘルパー呼び出しへ差し替え
  • 未使用の import（pytest）を削除

実装詳細:

  • extract_section_content() の戻り値を str | None に統一（既存は str で空文字列を返していたが、None の方が明確）
  • 既存の判定ロジック（check_section_not_empty, check_implementation_steps, check_file_list, check_validation_result）はテストファイル内に残し、ヘルパー関数を呼び出す形に変更

変更ファイル一覧

新規作成ファイル

  • tests/api/_completion_report_helpers.py - Completion Report 解析専用ヘルパー

変更ファイル

  • tests/api/test_completion_report_content_quality_gate.py - ヘルパー関数を使用するようにリファクタ

動作確認結果

テスト結果

実行コマンド:

python -m pytest tests/api/test_completion_reports_exist.py tests/api/test_completion_reports_for_completed_crs.py tests/api/test_completion_report_quality_gate.py tests/api/test_completion_report_content_quality_gate.py tests/api/test_readme_cr_status_quality_gate.py tests/api/test_readme_cr_entry_quality_gate.py -q

結果:

  • ✅ 全テスト: 11 passed
  • ✅ test_completion_report_content_quality_gate.py: PASS
  • ✅ 既存の品質ゲートテスト: すべて PASS

確認項目:

  • ✅ 既存テストの期待値は変更されていない（リファクタのみ）
  • ✅ 既存の品質ゲート仕様（判定ルール）は変わっていない
  • ✅ ヘルパー関数が正しく動作している

静的解析結果

  • リンターエラー: なし
  • 型チェック: 問題なし

設計上の改善点

保守性の向上

  1. 解析ロジックの共通化
    • Completion Report 解析ロジックが _completion_report_helpers.py に集約
    • 今後の品質ゲート拡張時に、同じロジックを再利用可能
  2. 責務の明確な分離
    • README 解析: _readme_cr_helpers.py
    • Completion Report 解析: _completion_report_helpers.py
    • 相互 import を禁止することで、責務境界を明確化
  3. テストコードの簡潔化
    • テストファイル内の重複ロジックを削減
    • テストコードが読みやすくなり、保守しやすくなった

拡張性の向上

  1. 将来の品質ゲート拡張に対応
    • 新しい品質ゲートを追加する際、既存のヘルパー関数を再利用可能
    • 解析ロジックの変更が一箇所に集約されるため、影響範囲が明確

既知の制約・注意事項

制約

  • 既存テストの期待値は変更していない（リファクタのみ）
  • 既存の品質ゲート仕様（判定ルール）は変えていない

注意事項

  • extract_section_content() の戻り値を str | None に統一（既存は str で空文字列を返していたが、None の方が明確）
  • README 解析と Completion Report 解析は混ぜない（責務境界を守る）

次のステップ

推奨アクション

  1. 他のテストファイルでのヘルパー活用
    • 今後、Completion Report 解析が必要なテストが増えた場合、_completion_report_helpers.py を活用
  2. ヘルパー関数の拡張
    • 必要に応じて、新しい解析ロジックを追加
    • 既存の関数を拡張する際は、後方互換性を維持

まとめ

CR-NEXUS-047 の実装により、Completion Report 解析ロジックがテスト専用ヘルパーに共通化されました。これにより、今後の品質ゲート拡張時に同じロジックを再利用できるようになり、保守コストと不整合リスクが削減されました。すべてのテストが PASS し、既存の期待値や判定ルールに影響を与えることなく、リファクタリングを完了しました。

This site uses Just the Docs, a documentation theme for Jekyll.