Skip to content

[docs] Add doc-drift guard tests: keep CLI flags, slash commands, config keys and EN/JA structure in sync #22

Description

@Kewton

背景 / 目的

READMEのフラグ記載が37個中約13個しかない等、ドキュメントとコードの乖離(doc drift)が既に起きている。今後リファレンス(docs/guide/)を整備しても、同期を保つ仕組みがなければ再び陳腐化する。**ドキュメントとコードの同期を機械検証するテスト(doc-drift guard)**を追加する。

前提: ユーザーガイド(docs/guide/)Issueの完了後に着手。

現状

  • CLIフラグの正: src/cli.rs のclap定義(37フラグ)。ヘルプ内容を検証する既存テストの前例あり(src/cli.rs:191,195-197--ux-demo --model-probe のhelp包含を確認)。
  • スラッシュコマンドの正: render_help(src/tui/slash.rs:408-429、15コマンド)とディスパッチ(:211-357)。
  • 設定キーの正: preset10キーのパーサ(src/config.rs:795-857)とトップレベルキー(:740-770)。
  • ドキュメント側(docs/guide/en|ja)は先行Issueで新設される。

要求仕様(受け入れ基準)

新しい統合テスト(例: tests/doc_drift.rs)として実装する:

1. CLIフラグ同期

  • clapの Command イントロスペクション(Cli::command().get_arguments())で全フラグ名を列挙し、docs/guide/en/cli-reference.md全フラグが出現することを検証する(方向は「コードにあるものがドキュメントに漏れなく載っている」。ドキュメント側の追加説明は自由)
  • 逆方向も検証: ドキュメントの表に載っているフラグ名が実在しないならfail(タイポ・削除済みフラグの検知)。表のパースは「行頭 | \--flag`` 形式」など単純な規約を決めてガイド側もそれに従う

2. スラッシュコマンド同期

  • render_help の出力からコマンド名(/xxx)を抽出し、docs/guide/en/slash-commands.md に全て出現することを検証(逆方向も同様)
  • 可能なら render_help とディスパッチ(handle_command)の一致もこの機会にテスト化する(helpに載っているのに処理がない/その逆の検知)

3. 設定キー同期

  • presetキー10個とトップレベルキーの一覧をテスト内の定数ではなくコードから導出できない場合は、src/config.rs 側に「サポートするキーの一覧」を返す関数(またはconst)を追加してそれを正とし、ドキュメント出現を検証する

4. 対訳同期(軽量)

  • docs/guide/en/docs/guide/ja/ファイル集合が一致することを検証
  • 各対訳ペアでh2/h3見出しの数が一致することを検証(内容の翻訳品質は対象外。構造の欠落だけ検知)

5. 運用

  • 失敗時のメッセージは「どのフラグ/コマンド/キーがどちら側に欠けているか」を列挙し、修正先ファイルパスを示す
  • CI(.github/workflows/ci.ymlcargo test --all-targets)で自動実行される(統合テストとして置けば追加設定不要のはず。要確認)

実装ガイド

  • ドキュメントのパースは正規表現ベースの最小実装でよい。Markdownパーサの依存追加はしない。
  • テストからの相対パスではなく env!("CARGO_MANIFEST_DIR") 基準でdocsを読む。
  • ガイド側の表規約(パース対象の書式)は本Issueで確定し、docs/guide/README.md に「この書式はテストで検証される」と明記する。

テスト / 検証

  • わざとフラグを1つ消す/追加する変更でテストがfailすることを手元で確認してから戻す(検知能力の確認)
  • cargo test --quiet 全通過

スコープ外

  • ドキュメント本文の執筆・修正(先行Issue)/ 翻訳品質の検証 / モデルID等、コード外の事実の検証

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationenhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions