fix: backlink/unresolved パネルの fileTreeVersion 即時再スキャンを debounce 化

[ymnao]

概要

backlink / unresolved-links パネルを開いたまま編集すると、autosave (既定 2s) の自己書込を watcher が拾い、約 2.5 秒毎にワークスペース全 .md の再読込スキャンが走り続ける問題を修正する。fileTreeVersion 起点の即時再スキャンを contentVersion 側と同じ 2000ms debounce に統合した。

関連 Issue

closes #298

移行 Stage

• Stage 0: 雛形 + フロント表示確認
• Stage 1: ファイル I/O
• Stage 2: ワークスペース・ファイルツリー・ファイル監視
• Stage 3: 全文検索（ripgrep sidecar）
• Stage 4: Git Sync
• Stage 5: OGP / PDF / アップデート
• Stage 6: 仕上げ・配布・切り替え

変更内容

• 共有 hook useDebouncedVersionRescan を新規追加: fileTreeVersion / contentVersion のどちらかが進んだら 2000ms 後に 1 回だけ rescan を呼ぶ (両カウンタとも +1 単調増加のため和 1 本で版比較)。cancel IPC は timer が発火して scan が実際に走った後の cleanup でのみ送信 (未発火時の無駄 IPC を排除)
• BacklinkPanel / UnresolvedLinksPanel の即時スキャン effect から scanVersion (= fileTreeVersion) を除去し、workspace / ターゲット変更 (+ mount) 時のみ即時スキャンに変更。従来の「即時 (fileTreeVersion) + 2 秒後 (contentVersion)」の二重実行も解消
• bumpFileTreeVersion の発火経路 (useFileWatcher / AppLayout) と FileTree・wikilinks キャッシュの即時性は不変更 (issue の確定設計どおり)
• 両パネルの component test を新規追加 (計 17 件、fake timers + workspace store 直接駆動)

動作確認

• typecheck 3 本 (node / web / e2e) PASS
• biome check 326 files PASS
• vitest 全件 2290 passed / 2 skipped (新規 17 件含む)
• codex-review 3 観点 (詳細は検証エビデンス)
• renderer-only / 実 Electron e2e は CI で確認 (ローカル sandbox は listen EPERM)

スクリーンショット

UI 変更なし

検証エビデンス

リスク分類

tier: high — classify-risk.sh の判定理由は agent-config: src/hooks/useDebouncedVersionRescan.ts。これは React hooks ディレクトリ (src/hooks/) をエージェント設定 (Claude hooks) とパスパターン誤マッチした false positive だが、下方修正せず high の手順 (codex-review 3 観点 + テスト + walkthrough) を実施した。

実行した検証

種別	コマンド	結果
型検査	tsc --noEmit -p tsconfig.node.json / tsconfig.web.json / tsconfig.e2e.json	PASS × 3
Lint	biome check .	PASS (326 files, No fixes applied)
テスト	vitest run (全件)	PASS: 103 files / 2290 passed, 2 skipped
e2e	renderer-only / 実 Electron	未実施 (ローカル sandbox で listen EPERM のため CI で確認)
レビュー	codex-review shell-senior	PASS (0 findings)
レビュー	codex-review security	PASS (0 findings)
レビュー	codex-review qa-fixture	初回 3 findings (3 confirmed → fixed) / confirm 再実行 5 findings (4 refuted, 1 confirmed → d001845 で fixed)

レビュー指摘と対応

qa-fixture 初回 (3 件、全て CONFIRMED → テスト追加で fix、623b0b7 に fold):

severity/conf	対象	指摘	対応
MEDIUM/90	useDebouncedVersionRescan.ts:23	!rescan (null target) 分岐が未テスト	CONFIRMED+FIXED — 「activeTabPath が null では version が進んでも scan されない」を追加
MEDIUM/95	useDebouncedVersionRescan.ts:34	fired 後 cleanup の cancel 分岐が未テスト	CONFIRMED+FIXED — 「debounce 発火後の cleanup では cancel*Scan が送られる」を両パネルに追加
MEDIUM/88	useDebouncedVersionRescan.ts:30	timer 未発火 cleanup で cancel しない仕様が未テスト	CONFIRMED+FIXED — 「timer 未発火の cleanup では cancel*Scan が送られない」を両パネルに追加

qa-fixture confirm 再実行 (5 件):

severity/conf	対象	指摘	対応
MEDIUM/85	useDebouncedVersionRescan.ts:24	null 期間中の version 進行 → 非 null 復帰時の挙動が未テスト	CONFIRMED+FIXED (d001845) — 復帰時は即時 scan に加え遅延 scan が 1 回走る (旧実装と同一挙動) をテストで固定。skill 規定 (max 2 runs) により codex の再々実行は行わず、指摘内容の解消をテストで確認
MEDIUM/80	useDebouncedVersionRescan.ts:32	staggered な連続 bump が未テスト	REFUTED — 追加済みの「timer 未発火の cleanup」テストが bump → 1000ms → 再 bump → 2000ms → scan 1 回を検証済み
MEDIUM/85	useDebouncedVersionRescan.ts:34	fired 分岐が未テスト	REFUTED — 初回指摘 2 で追加済み (codex は committed diff を参照しており未コミットのテスト追加が不可視だった stale 指摘)
LOW/75	BacklinkPanel.test.tsx:55	afterEach で useRealTimers に戻していない	REFUTED — src/test-setup.ts のグローバル afterEach が全テストで real timers 復帰を保証 (リポジトリ確立済みの構成)
LOW/75	UnresolvedLinksPanel.test.tsx:55	同上	REFUTED — 同上

/simplify (4 観点並列レビュー、適用済み)

• Altitude/Reuse/Simplification: debounce ロジックの 2 パネル逐語重複 → useDebouncedVersionRescan hook へ抽出
• Simplification: {tree, content} ペア ref → 単調増加カウンタの和 1 本へ
• Efficiency: timer 未発火 cleanup の無条件 cancel IPC → fired フラグで発火後のみ
• Reuse: テストの冗長 afterEach(vi.useRealTimers) 削除 (グローバル setup と重複)
• 見送り: maxWait 付き debounce (注記レベル) / 生カウンタ購読による再レンダリング (diff 前からの構造) / テスト共有ハーネス化 (過剰抽象)

🤖 Generated with Claude Code