diff --git a/GLOSSARY.md b/GLOSSARY.md index 1725fa4..ef78538 100644 --- a/GLOSSARY.md +++ b/GLOSSARY.md @@ -24,6 +24,12 @@ A label describing an endgame's technique or goal, such as "mate in 2", "Lucena" "opposition"; an endgame can carry several. _Avoid_: Tag, label, category +**Key**: +The canonical material signature of an endgame's starting position — which +pieces each side has, written strongest side first and colour-agnostic +(e.g. "KQ v KR"). Used to group and search endgames by material. +_Avoid_: Material signature, hash + ## Play **Winning side**: diff --git a/docs/adr/0003-canonical-material-key.md b/docs/adr/0003-canonical-material-key.md new file mode 100644 index 0000000..083c41c --- /dev/null +++ b/docs/adr/0003-canonical-material-key.md @@ -0,0 +1,10 @@ +# Canonical, colour-agnostic material Key for endgames + +An endgame's `key` is derived from its FEN rather than typed by hand, as the +material signature of the start position: each side's pieces, strongest side +first by material value (`Q=9, R=5, B=3, N=3, P=1`) and colour-agnostic, so +`KQ v KR` is the same key whichever colour has the queen. Bishop square colour +is not encoded. We chose this over a white-vs-black ordering or a free-text key +so endgames with the same material group together regardless of colour, and so +the key can never drift from the position; side-to-move and outcome stay in the +`color` and `result` fields. diff --git a/lib/chesstrainer/endgames/endgame.ex b/lib/chesstrainer/endgames/endgame.ex index 791ecba..695606a 100644 --- a/lib/chesstrainer/endgames/endgame.ex +++ b/lib/chesstrainer/endgames/endgame.ex @@ -6,6 +6,8 @@ defmodule Chesstrainer.Endgames.Endgame do use Ecto.Schema import Ecto.Changeset + alias Chesstrainer.Key + @primary_key {:id, :binary_id, autogenerate: true} @foreign_key_type :binary_id schema "endgames" do @@ -30,12 +32,9 @@ defmodule Chesstrainer.Endgames.Endgame do @doc false def changeset(endgame, attrs) do endgame - |> cast(normalize_attrs(attrs), [:fen, :key, :message, :notes, :result, :rating, :color]) + |> cast(normalize_attrs(attrs), [:fen, :message, :notes, :result, :rating, :color]) |> validate_required([:fen, :color], message: "Invalid FEN") - |> validate_required([:key, :result, :rating]) - |> validate_format(:key, ~r/^(?=.{5,10}$)KQ*R*[NB]*P*\sv\sKQ*R*[NB]*P*$/, - message: "Key must follow pattern KQ.. v KQR.., max pieces 7" - ) + |> validate_required([:result, :rating]) |> validate_change(:fen, fn :fen, fen -> case fen_issues(fen) do [] -> [] @@ -43,6 +42,14 @@ defmodule Chesstrainer.Endgames.Endgame do end end) |> unique_constraint(:fen, message: "FEN already exists") + |> put_key() + end + + defp put_key(changeset) do + case Key.from_fen(get_field(changeset, :fen)) do + {:ok, key} -> put_change(changeset, :key, key) + {:error, :invalid_fen} -> changeset + end end defp normalize_attrs(%{"fen" => fen} = attrs) when is_binary(fen), diff --git a/lib/chesstrainer/key.ex b/lib/chesstrainer/key.ex new file mode 100644 index 0000000..04818c5 --- /dev/null +++ b/lib/chesstrainer/key.ex @@ -0,0 +1,124 @@ +defmodule Chesstrainer.Key do + @moduledoc """ + Derives an endgame's canonical material Key from its FEN. + + The Key is a color-agnostic material signature: each side's pieces, stronger + side first, for example `"KQ v KR"`. It ignores piece placement and bishop + square colour. Within a side the pieces are written `K`, then `Q`, `R`, `B`, + `N`, `P`; the two sides are ordered by material value + (`Q=9, R=5, B=3, N=3, P=1`, kings ignored). + """ + + @piece_order [{"q", "Q"}, {"r", "R"}, {"b", "B"}, {"n", "N"}, {"p", "P"}] + @values %{"q" => 9, "r" => 5, "b" => 3, "n" => 3, "p" => 1} + @pieces ~w(p n b r q k P N B R Q K) + @digits ~w(1 2 3 4 5 6 7 8) + + @doc """ + Returns the canonical material Key for a FEN. + + ## Examples + + iex> Chesstrainer.Key.from_fen("8/8/3k4/8/8/3K1R2/8/8 w - - 0 1") + {:ok, "KR v K"} + + iex> Chesstrainer.Key.from_fen("6k1/5p2/6p1/8/7p/8/6PP/6K1 b - - 0 1") + {:ok, "KPPP v KPP"} + + iex> Chesstrainer.Key.from_fen("not a fen") + {:error, :invalid_fen} + """ + @spec from_fen(String.t() | nil) :: {:ok, String.t()} | {:error, :invalid_fen} + def from_fen(fen) when is_binary(fen) do + with [board | _] <- String.split(fen), + {:ok, white, black} <- parse_board(board) do + {:ok, join_sides(white, black)} + else + _ -> {:error, :invalid_fen} + end + end + + def from_fen(_fen), do: {:error, :invalid_fen} + + defp parse_board(board) do + ranks = String.split(board, "/") + + result = + if length(ranks) == 8 do + Enum.reduce_while( + ranks, + {:ok, %{"w" => new_counts(), "b" => new_counts()}}, + fn rank, {:ok, acc} -> + case add_rank(rank, acc) do + {:ok, acc} -> {:cont, {:ok, acc}} + :error -> {:halt, :error} + end + end + ) + else + :error + end + + case result do + {:ok, %{"w" => white, "b" => black}} -> {:ok, white, black} + :error -> :error + end + end + + defp new_counts, do: Map.new(~w(k q r b n p), &{&1, 0}) + + defp add_rank(rank, acc) do + rank + |> String.graphemes() + |> Enum.reduce_while({0, acc}, fn char, {squares, acc} -> + cond do + char in @digits -> + {:cont, {squares + String.to_integer(char), acc}} + + char in @pieces -> + side = if char == String.downcase(char), do: "b", else: "w" + piece = String.downcase(char) + + counts = + acc + |> Map.fetch!(side) + |> Map.update!(piece, &(&1 + 1)) + + {:cont, {squares + 1, Map.put(acc, side, counts)}} + + true -> + {:halt, :error} + end + end) + |> case do + {8, acc} -> {:ok, acc} + _ -> :error + end + end + + defp join_sides(white, black) do + {first, second} = order_sides(white, black) + "#{side_string(first)} v #{side_string(second)}" + end + + defp side_string(counts) do + "K" <> + Enum.map_join(@piece_order, fn {lower, upper} -> + String.duplicate(upper, counts[lower]) + end) + end + + defp order_sides(white, black) do + if rank(white) >= rank(black), do: {white, black}, else: {black, white} + end + + defp rank(counts) do + {value(counts), counts["q"], counts["r"], counts["b"], counts["n"], counts["p"]} + end + + defp value(counts) do + Enum.reduce(@values, 0, fn {piece, weight}, total -> + total + counts[piece] * weight + end) + end +end diff --git a/lib/chesstrainer_web/live/endgame_live/form.ex b/lib/chesstrainer_web/live/endgame_live/form.ex index 3549af5..30ce00f 100644 --- a/lib/chesstrainer_web/live/endgame_live/form.ex +++ b/lib/chesstrainer_web/live/endgame_live/form.ex @@ -73,7 +73,6 @@ defmodule ChesstrainerWeb.EndgameLive.Form do <.form for={@form} id="endgame-form" phx-change="validate" phx-submit="save"> <.input field={@form[:fen]} type="text" label="Fen" disabled={@live_action == :edit} /> <.input field={@form[:color]} type="text" label="Color" disabled /> - <.input field={@form[:key]} type="text" label="Key" /> <.input field={@form[:rating]} type="number" label="Rating" /> <.input field={@form[:message]} type="textarea" label="Message" /> <.input field={@form[:notes]} type="textarea" label="Notes" /> diff --git a/priv/repo/migrations/20251127164545_create_endgames.exs b/priv/repo/migrations/20251127164545_create_endgames.exs index b100576..72c4193 100644 --- a/priv/repo/migrations/20251127164545_create_endgames.exs +++ b/priv/repo/migrations/20251127164545_create_endgames.exs @@ -19,5 +19,6 @@ defmodule Chesstrainer.Repo.Migrations.CreateEndgames do end create unique_index(:endgames, [:fen]) + create index(:endgames, [:key]) end end diff --git a/priv/repo/seeds.exs b/priv/repo/seeds.exs index 0825c96..a3442d2 100644 --- a/priv/repo/seeds.exs +++ b/priv/repo/seeds.exs @@ -18,32 +18,33 @@ now = DateTime.utc_now() |> DateTime.truncate(:second) IO.puts("🌱 Seeding basic endgames into DB...") +endgames = [ + %{ + fen: "8/8/3k4/8/8/3K1R2/8/8 w - - 0 1", + color: :white, + message: "Rook vs king endgame", + notes: "Basic rook endgame", + result: :win + }, + %{ + fen: "6k1/5p2/6p1/8/7p/8/6PP/6K1 b - - 0 1", + color: :black, + message: "3 pawns vs 2 pawns", + notes: "https://www.chessgames.com/perl/chessgame?gid=1017147", + result: :win + } +] + Repo.insert_all( Endgame, - [ - %{ - id: Ecto.UUID.generate(), - fen: "8/8/3k4/8/8/3K1R2/8/8 w - - 0 1", - color: :white, - key: "KR v K", - message: "Rook vs king endgame", - notes: "Basic rook endgame", - result: :win, - inserted_at: now, - updated_at: now - }, - %{ - id: Ecto.UUID.generate(), - fen: "6k1/5p2/6p1/8/7p/8/6PP/6K1 b - - 0 1", - color: :black, - key: "KPPP v KPP", - message: "3 pawns vs 2 pawns", - notes: "https://www.chessgames.com/perl/chessgame?gid=1017147", - result: :win, - inserted_at: now, - updated_at: now - } - ], + Enum.map(endgames, fn endgame -> + {:ok, key} = Chesstrainer.Key.from_fen(endgame.fen) + + endgame + |> Map.put(:id, Ecto.UUID.generate()) + |> Map.put(:key, key) + |> Map.merge(%{inserted_at: now, updated_at: now}) + end), on_conflict: :nothing ) diff --git a/test/chesstrainer/endgames_test.exs b/test/chesstrainer/endgames_test.exs index 34a75e3..471dc54 100644 --- a/test/chesstrainer/endgames_test.exs +++ b/test/chesstrainer/endgames_test.exs @@ -6,23 +6,47 @@ defmodule Chesstrainer.EndgamesTest do alias Chesstrainer.Themes describe "create_endgame/1 FEN validation" do - test "accepts a standard valid FEN" do + test "accepts a standard valid FEN and derives its key" do attrs = %{ fen: "8/8/3k4/8/8/3K1R2/8/8 w - - 0 1", color: :white, - key: "KR v K", result: :win, rating: 1500 } - assert {:ok, %Endgame{}} = Endgames.create_endgame(attrs) + assert {:ok, %Endgame{} = endgame} = Endgames.create_endgame(attrs) + assert endgame.key == "KR v K" + end + + test "derives the key from the strongest side, colour-agnostically" do + attrs = %{ + fen: "6k1/5p2/6p1/8/7p/8/6PP/6K1 b - - 0 0", + color: :black, + result: :win, + rating: 1500 + } + + assert {:ok, endgame} = Endgames.create_endgame(attrs) + assert endgame.key == "KPPP v KPP" + end + + test "ignores a supplied key and derives it from the FEN" do + attrs = %{ + fen: "8/8/3k4/8/8/3K1R2/8/8 w - - 0 1", + color: :white, + key: "KQ v K", + result: :win, + rating: 1500 + } + + assert {:ok, endgame} = Endgames.create_endgame(attrs) + assert endgame.key == "KR v K" end test "normalizes fullmove 0 to 1 before inserting" do attrs = %{ fen: "6k1/5p2/6p1/8/7p/8/6PP/6K1 b - - 0 0", color: :black, - key: "KPPP v KPP", result: :win, rating: 1500 } @@ -35,7 +59,6 @@ defmodule Chesstrainer.EndgamesTest do attrs = %{ fen: " 8/8/3k4/8/8/3K1R2/8/8 w - - 0 1\t\n", color: :white, - key: "KR v K", result: :win, rating: 1500 } @@ -48,7 +71,6 @@ defmodule Chesstrainer.EndgamesTest do attrs = %{ fen: "4k3/8/8/8/8/8/8/0K7 w - - 0 1", color: :white, - key: "KQ v K", result: :win, rating: 1500 } @@ -62,7 +84,6 @@ defmodule Chesstrainer.EndgamesTest do attrs = %{ fen: "8/8/3k4/8/8/3K1R2/8/8", color: :white, - key: "KQ v K", result: :win, rating: 1500 } @@ -76,7 +97,6 @@ defmodule Chesstrainer.EndgamesTest do attrs = %{ fen: "8/8/3k4/8/8/3K1R2/8/8 x - - 0 1", color: :white, - key: "KQ v K", result: :win, rating: 1500 } @@ -94,7 +114,6 @@ defmodule Chesstrainer.EndgamesTest do attrs = %{ fen: "8/8/3k4/8/8/3K1R2/8/8 w - - 0 1", color: :white, - key: "KR v K", result: :win, rating: 1500 } @@ -110,7 +129,6 @@ defmodule Chesstrainer.EndgamesTest do attrs = %{ fen: "6k1/5p2/6p1/8/7p/8/6PP/6K1 b - - 0 1", color: :black, - key: "KPPP v KPP", result: :win, rating: 1500 } @@ -118,6 +136,7 @@ defmodule Chesstrainer.EndgamesTest do assert {:ok, endgame} = Endgames.create_endgame(attrs, [lucena]) assert {:ok, updated} = Endgames.update_endgame(endgame, %{rating: 1600}, [philidor]) assert Enum.map(updated.themes, & &1.id) == [philidor.id] + assert updated.key == "KPPP v KPP" end end end diff --git a/test/chesstrainer/key_test.exs b/test/chesstrainer/key_test.exs new file mode 100644 index 0000000..bac483e --- /dev/null +++ b/test/chesstrainer/key_test.exs @@ -0,0 +1,39 @@ +defmodule Chesstrainer.KeyTest do + use ExUnit.Case, async: true + + doctest Chesstrainer.Key + + alias Chesstrainer.Key + + describe "from_fen/1" do + test "derives a rook endgame" do + assert Key.from_fen("8/8/3k4/8/8/3K1R2/8/8 w - - 0 1") == {:ok, "KR v K"} + end + + test "is colour-agnostic" do + white_queen = "8/8/3k1r2/8/8/3K1Q2/8/8 w - - 0 1" + black_queen = "8/8/3k1q2/8/8/3K1R2/8/8 w - - 0 1" + + assert Key.from_fen(white_queen) == {:ok, "KQ v KR"} + assert Key.from_fen(black_queen) == {:ok, "KQ v KR"} + end + + test "puts the side with more material first" do + assert Key.from_fen("6k1/5p2/6p1/8/7p/8/6PP/6K1 b - - 0 1") == {:ok, "KPPP v KPP"} + end + + test "orders equal-value sides deterministically" do + white_bishop = "8/8/3k1n2/8/8/3K1B2/8/8 w - - 0 1" + white_knight = "8/8/3k1b2/8/8/3K1N2/8/8 w - - 0 1" + + assert Key.from_fen(white_bishop) == {:ok, "KB v KN"} + assert Key.from_fen(white_knight) == {:ok, "KB v KN"} + end + + test "returns an error for malformed FENs" do + assert Key.from_fen("not a fen") == {:error, :invalid_fen} + assert Key.from_fen("8/8/8 w - - 0 1") == {:error, :invalid_fen} + assert Key.from_fen(nil) == {:error, :invalid_fen} + end + end +end diff --git a/test/chesstrainer_web/live/endgame_live/form_test.exs b/test/chesstrainer_web/live/endgame_live/form_test.exs index e6b1c80..7d06d43 100644 --- a/test/chesstrainer_web/live/endgame_live/form_test.exs +++ b/test/chesstrainer_web/live/endgame_live/form_test.exs @@ -20,7 +20,7 @@ defmodule ChesstrainerWeb.EndgameLive.FormTest do view |> form("#endgame-form", - endgame: %{fen: @fen, key: "KR v K", rating: 1500, result: "win"} + endgame: %{fen: @fen, rating: 1500, result: "win"} ) |> render_submit() @@ -62,7 +62,7 @@ defmodule ChesstrainerWeb.EndgameLive.FormTest do test "removes a theme from an existing endgame", %{conn: conn} do theme = theme_fixture(%{name: "Lucena"}) - attrs = %{fen: @fen, color: :white, key: "KR v K", result: :win, rating: 1500} + attrs = %{fen: @fen, color: :white, result: :win, rating: 1500} {:ok, endgame} = Endgames.create_endgame(attrs, [theme]) {:ok, view, _html} = live(conn, ~p"/admin/endgames/#{endgame}/edit") @@ -72,7 +72,7 @@ defmodule ChesstrainerWeb.EndgameLive.FormTest do view |> element("button[aria-label='Remove Lucena']") |> render_click() view - |> form("#endgame-form", endgame: %{key: "KR v K", rating: 1500, result: "win"}) + |> form("#endgame-form", endgame: %{rating: 1500, result: "win"}) |> render_submit() assert_redirect(view, ~p"/admin/endgames") diff --git a/test/chesstrainer_web/live/endgame_live/play_test.exs b/test/chesstrainer_web/live/endgame_live/play_test.exs index 168b39a..cbba826 100644 --- a/test/chesstrainer_web/live/endgame_live/play_test.exs +++ b/test/chesstrainer_web/live/endgame_live/play_test.exs @@ -78,7 +78,14 @@ defmodule ChesstrainerWeb.EndgameLive.PlayTest do end test "shows endgame metadata in the header", %{conn: conn} do - endgame = endgame_fixture(key: "KQ v K", color: :white, result: :win, rating: 1800) + endgame = + endgame_fixture( + fen: "8/8/3k4/8/8/3K1Q2/8/8 w - - 0 1", + color: :white, + result: :win, + rating: 1800 + ) + seed_tablebase(endgame.fen) {:ok, _view, html} = live(conn, ~p"/endgames/#{endgame}/play") diff --git a/test/support/fixtures/endgame_fixtures.ex b/test/support/fixtures/endgame_fixtures.ex index 0876a5c..9e9c200 100644 --- a/test/support/fixtures/endgame_fixtures.ex +++ b/test/support/fixtures/endgame_fixtures.ex @@ -24,15 +24,13 @@ defmodule Chesstrainer.EndgamesFixtures do @doc """ Generate an endgame. - A simple K v K position with a unique FEN, color, - key, rating, and result. + A simple K v K position with a unique FEN, color, rating, and result. """ def endgame_fixture(attrs \\ %{}) do {:ok, endgame} = attrs |> Enum.into(%{ fen: unique_endgame_fen(), - key: "KQ v K", color: :white, result: :win, rating: 1500