feat: flat_map と group_map を追加する

[Javakky]

概要（What / Why）

callback の戻り配列を 1 段だけ平坦化する flat_map と、group_by しつつ各要素を変換する group_map を追加します。

変更点

• src/flat_map.php — LIST は連番へ正規化、ASSOC は callback 戻りのキーを採用 (衝突は後勝ち)
• src/group_map.php — group_by とキーの扱いを揃え、各要素を $transform で変換
• tests/FlatMapTest.php (12 ケース) / tests/GroupMapTest.php (8 ケース)
• composer.json の autoload.files に 2 件追加

動作確認

• 手動：
  • flat_map([1, 2], fn ($v) => [$v, $v * 10]) → [1, 10, 2, 20]
  • group_map(['alice' => 20, 'bob' => 17], fn ($age) => $age >= 20 ? 'adult' : 'minor', fn ($age) => $age * 12) → ['adult' => ['alice' => 240], 'minor' => ['bob' => 204]]
• 自動：
  • vendor/bin/php-cs-fixer fix --dry-run --diff / vendor/bin/phpstan analyse -c phpstan.neon / vendor/bin/phpunit tests
  • 結果：OK (117 tests, 122 assertions) / PHPStan level 10 [OK] No errors / CS Fixer Fixed 0 of 33 files

補足（任意）

flat_map の平坦化は 1 段だけ

戻り配列の中の配列は展開しません (phpdoc に明記、テストで固定)。

MODE_ASSOC は外側キーを捨てる

入力側のキーではなく callback 戻り配列のキーを採用し、衝突は後勝ちです。テストでは値が後勝ちになることに加えてキーの位置が初出のまま残ることまで固定しています (PHP の上書きはキー位置を移動しないため)。

list 入力に MODE_ASSOC を明示すると callback 戻りの内側キーが全部 0 になって 1 件に潰れます。仕様からは正しいものの驚きやすい組み合わせなので、これもテストで固定しました。

@template R of array-key が解決されることを確認済み

callback が list を返す呼び出しで R が推論されず array<never, E> に落ちる懸念がありましたが、\PHPStan\dumpType() で 7 パターン確認したところ 1 件も出ませんでした (list 戻りのケースは array<0, 1|2> と解決され、実行時結果 [0 => 2] を正しく含みます)。

group_map は Mode を取りません

group_by と同じく入力形状でキーの扱いを決めます (list 入力なら各グループは list、assoc 入力なら元のキーを保持)。

Closes #57
Closes #20

🤖 Generated with Claude Code

---

追記: group_map に Mode を追加しました

新規関数には Mode を持たせる方針に合わせました。当初は「group_by が取らないから」という理由で省いていましたが、それは既存関数の制約であって新規関数が従う理由になりません。

function group_map(array $input, callable $classifier, callable $transform, Mode $mode = Mode::MODE_AUTO): array

• MODE_LIST: 各グループが完全な list (入力が assoc でもキーを捨てる)
• MODE_ASSOC: 各グループが元のキーを維持 (list 入力でも元の整数添字を維持し、添字を詰めない)
• MODE_AUTO: array_is_list() 判定で group_by と同じ挙動 = 既存テストはすべてそのまま通ります

実装は array_is_list($input) の直接呼び出しをやめて Mode::check_mode($mode, $input) に置き換え、@phpstan-return を 4 分岐の条件型にしました。

OK (126 tests, 133 assertions) / PHPStan level 10 [OK] No errors。

Note

group_by 自体は Mode を持たないままなので、group_map(..., MODE_LIST) に相当する挙動が group_by にはありません。既存関数への追随は別途相談させてください。