feat: add documentation sync checker script

[keito4]

Summary

Add a CI script that verifies generated documentation is synchronized with code changes, preventing documentation drift.

Changes

• ✨ Add script/check-docs-sync.sh for verifying doc synchronization
• 📝 Create script/README.md with comprehensive script documentation
• 📋 Include CI integration examples and usage guidelines
• ⚙️ Support customization via environment variables
• 💬 Provide clear error messages and fix instructions

Key Features

Documentation Sync Checker

The script ensures developers keep generated documentation in sync with code:

How It Works:

1. Creates a backup of current documentation
2. Runs the documentation generation command
3. Compares generated docs with the original
4. Fails with helpful error message if differences are found

Configuration

Customizable via environment variables:

# Documentation generation command (default: npm run docs:generate)
export DOC_GENERATE_CMD="pnpm run docs:generate"

# Documentation directory (default: docs)
export DOCS_DIR="documentation"

Output Examples

Success:

📚 Checking documentation sync...
📝 Generating documentation...
🔍 Comparing documentation...
✅ Documentation is in sync!

Failure:

📚 Checking documentation sync...
❌ ERROR: Generated documentation is out of sync!

Please run the following command and commit the changes:
  npm run docs:generate

Integration

CI Workflow

- name: Check documentation sync
  run: ./script/check-docs-sync.sh

Package.json Scripts

{
  "scripts": {
    "docs:generate": "your-doc-generator-command",
    "docs:check": "./script/check-docs-sync.sh"
  }
}

Use Cases

• Projects with auto-generated API documentation
• Template-based documentation systems
• Schema-driven documentation
• Any project where docs are generated from code/metadata

Benefits

• ✅ Prevents stale documentation
• ✅ No manual doc update reminders needed
• ✅ Catches issues before merge
• ✅ Clear error messages with fix commands
• ✅ Lightweight (simple bash script, no dependencies)

Fixes #224

🤖 Generated with Claude Code

[coderabbitai]

Warning

Rate limit exceeded

@keito4 has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 24 minutes and 35 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📥 Commits

Reviewing files that changed from the base of the PR and between 11be2f2 and 003fbcb.

📒 Files selected for processing (2)

• script/README.md
• script/check-docs-sync.sh

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[claude]

PR レビュー: Documentation Sync Checker Script

このPRを確認しました。全体的に良い機能追加ですが、リポジトリの品質基準に照らしていくつかの改善点があります。

---

🔴 Critical Issues

1. テストカバレッジ不足 (TDD違反)

CLAUDE.md の要件:

• TDD原則: Red → Green → Refactor
• 70%+ 行カバレッジ必須

問題点:

• script/check-docs-sync.sh の Bats 統合テストが存在しない
• 他のスクリプト(setup-claude.sh, verify-container-setup.sh等)にはすべて対応する .bats テストファイルが存在

必要な対応:
test/integration/check_docs_sync.bats を作成

参考例: test/integration/setup_claude.bats

最低限必要なテストケース:

• スクリプトの存在と実行権限確認
• set -euo pipefail の使用確認
• 環境変数のデフォルト値確認
• 色定数の定義確認
• エラーメッセージの存在確認
• 一時ディレクトリのクリーンアップ確認

2. CI統合が不完全

問題点:

• .github/workflows/ci.yml にこのスクリプトのチェックが追加されていない
• 現時点で docs/ ディレクトリが存在せず、npm run docs:generate コマンドも未定義

推奨対応:
package.json に docs:generate, docs:check, docs:all スクリプト追加

---

⚠️ Important Issues

3. セキュリティ: eval の使用

script/check-docs-sync.sh:42
eval "$DOC_GENERATE_CMD" はインジェクション攻撃のリスクあり

推奨改善:
bash -c を使用するか、環境変数を配列化

4. エラーハンドリングの改善余地

script/check-docs-sync.sh:42-46
エラー出力を /dev/null に捨てているため、失敗理由が不明

---

📝 Minor Issues

• 一時ディレクトリ名に識別用プレフィックス追加推奨: mktemp -d -t docs-sync-check.XXXXXX
• diff コマンドに -q オプション追加推奨
• 日本語コメント不足(他のスクリプトとの一貫性)

---

✅ Good Points

1. 明確な責務分離
2. エラーメッセージの親切さ
3. カラー出力で視認性が高い
4. トラップハンドラによる一時ファイルのクリーンアップ
5. 環境変数によるカスタマイズ性
6. README.md の充実

---

🎯 Action Items (優先順位順)

1. [BLOCKER] test/integration/check_docs_sync.bats を作成 (TDD要件)
2. [HIGH] package.json にスクリプト追加
3. [HIGH] eval を bash -c に変更
4. [MEDIUM] エラー出力を捨てずにログ表示

---

📊 Quality Gate Status

項目	ステータス
Integration Tests	❌ check_docs_sync.bats 不足
Security	⚠️ eval 使用
Code Coverage	❌ 0% (テスト無し)

総合判定: 🔴 マージ不可 (TDD要件未達成)

---

修正後に再レビューをリクエストしてください。コンセプトは excellent ですが、品質基準を満たすためにテストが必須です!

[github-actions]

🎉 This PR is included in version 1.29.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀