docs: add crate test validity reports

2026-06-12 18:50:14 +09:00
parent 74b655df0e
commit a010c8f94b
23 changed files with 2268 additions and 0 deletions
@@ -0,0 +1,85 @@
+# テスト妥当性レビュー: project-record
+- 評価: 概ね良い
+
+## 確認範囲
+
+- Workspace root: `/home/hare/Projects/yoi`
+- Crate: `crates/project-record`
+- Main source/test file: `crates/project-record/src/lib.rs`
+- Crate の責務:
+  - Unix epoch milliseconds を、path-safe な固定幅13文字の Crockford base32 風 ID に encode/decode する。
+  - ID の validation を提供する。
+  - collision 時に suffix を付けず、millisecond 値を bounded に increment して未使用 ID を割り当てる。
+  - Ticket / Objective などの project record ID 生成・検証の共通基盤になっている。
+
+## 現在のテストがよくカバーしていること
+
+- `encode_unix_epoch_millis` の基本境界を押さえている。
+  - `0 -> 0000000000000`
+  - `31 -> 000000000000Z`
+  - `32 -> 0000000000010`
+- 固定幅 ID の lexicographic order が numeric / chronological order と一致する、というこの crate の重要 invariant を明示的にテストしている。
+- ambiguous / path-unsafe な文字を reject するテストがある。
+  - `I`, `L`, `O`, `/` を拒否しており、path-safe ID としての意図は確認できる。
+- decode overflow 相当のケースも一応含まれている。
+  - `ZZZZZZZZZZZZZ` は文字種としては valid だが `u64` を超えるため invalid になる。
+- collision allocation の基本動作を押さえている。
+  - 既存 ID と衝突したら `base_millis + 1` を使う。
+  - 全候補が衝突する場合は `MAX_COLLISION_PROBES` で bounded に失敗する。
+
+## 不足 / 疑問のあるテスト
+
+- encode/decode の round-trip coverage が薄い。
+  - `decode_unix_epoch_millis("0000000000010") == 32` 以外は decode の成功系がほぼ確認されていない。
+  - `u64::MAX`、現在時刻に近い値、桁境界、複数の代表値で `decode(encode(x)) == x` を見ると、crate の中心 invariant がより強くなる。
+- `decode_digit` の valid alphabet coverage が不足している。
+  - 現在の成功系 decode は主に `0`, `1` 周辺に偏っている。
+  - `A-H`, `J-K`, `M-N`, `P-T`, `V-Z` の range 分岐が壊れても一部は検出しにくい。
+- overflow 境界が明確にテストされていない。
+  - `decode("FZZZZZZZZZZZZ") == u64::MAX`
+  - `decode("G000000000000")` や `decode("ZZZZZZZZZZZZZ")` が `TimestampOverflow`
+  のように、13桁 base32 が 65bit 空間であることに由来する境界を分けて確認したい。
+- `rejects_ambiguous_or_path_unsafe_characters` は少し名前と中身が混ざっている。
+  - `ZZZZZZZZZZZZZ` は ambiguous/path-unsafe character ではなく numeric overflow なので、invalid character 系と overflow 系は別テストにした方が失敗時の意味が明確になる。
+- `allocate_record_id` の overflow 経路が未テスト。
+  - `base_millis == u64::MAX` かつ最初の候補が衝突した場合、次の probe で `TimestampOverflow` になるはず。
+  - collision boundedness だけでなく、上限付近の arithmetic safety を確認したい。
+- lowercase policy がテストされていない。
+  - Crockford base32 という名前からは lowercase 許容を期待する読者もいるため、この実装が uppercase-only なら `a`, `z` などを reject するテストか、仕様コメントでの明示があると良い。
+- `unix_epoch_millis_now` は実質未テスト。
+  - `SystemTime::now()` wrapper なので優先度は低いが、少なくとも「現在の正常環境で `Ok` を返す」程度の smoke test は可能。
+  - ただし時刻依存なので、無理に強い assertion を置く必要はない。
+
+## 追加を提案するテスト
+
+- 代表値での round-trip test:
+  - `0`
+  - `1`
+  - `31`
+  - `32`
+  - `33`
+  - `1024`
+  - 現在時刻近辺の固定値
+  - `u64::MAX`
+- decode boundary tests:
+  - `FZZZZZZZZZZZZ` が `u64::MAX` に decode されること。
+  - `G000000000000` や `ZZZZZZZZZZZZZ` が `TimestampOverflow` になること。
+- alphabet mapping test:
+  - `RECORD_ID_ALPHABET` の各文字を下位桁に置いた ID を decode し、index と一致すること。
+- invalid character test の分割:
+  - ambiguous chars: `I`, `L`, `O`
+  - lowercase chars: `a`, `z` など、uppercase-only policy を明示する場合
+  - path separators / unsafe chars: `/`, `\`, `.`, maybe whitespace
+  - overflow: valid alphabet だが `u64` 範囲外
+- allocation overflow test:
+  - `allocate_record_id(u64::MAX, |_| true)` が `TimestampOverflow` になること。
+- allocation probe behavior test:
+  - `exists` が必要以上に呼ばれないこと、また最初の available candidate で止まることを確認すると、bounded allocation の仕様がより明確になる。
+
+## 実行したコマンド
+
+- `cargo test -p project-record`
+  - 結果: pass
+  - 概要: 5 unit tests passed, 0 failed; doc-tests 0 passed / 0 failed.
+  - 注記: artifact directory の file lock 待ちがあったが、テスト妥当性評価に影響する失敗ではない。
+