mirror of
https://github.com/TheRealOwenRees/chess-endgame-trainer.git
synced 2026-11-18 11:42:07 +00:00
Derive canonical material Key from the FEN
The Endgame key is now a canonical, colour-agnostic material signature derived from the FEN instead of a hand-typed field: each side's pieces, strongest side first by material value (e.g. "KQ v KR"). This fixes the seed ordering inconsistency and guarantees the key always matches the position. - Add Chesstrainer.Key.from_fen/1. - Compute the key in the Endgame changeset; drop the manual input and its regex validation. - Index endgames.key and derive keys in the seeds. - Document the Key term and the decision (ADR 0003). Closes #13
This commit is contained in:
@@ -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**:
|
||||
|
||||
@@ -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.
|
||||
@@ -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),
|
||||
|
||||
@@ -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
|
||||
@@ -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" />
|
||||
|
||||
@@ -19,5 +19,6 @@ defmodule Chesstrainer.Repo.Migrations.CreateEndgames do
|
||||
end
|
||||
|
||||
create unique_index(:endgames, [:fen])
|
||||
create index(:endgames, [:key])
|
||||
end
|
||||
end
|
||||
|
||||
+15
-14
@@ -18,32 +18,33 @@ now = DateTime.utc_now() |> DateTime.truncate(:second)
|
||||
|
||||
IO.puts("🌱 Seeding basic endgames into DB...")
|
||||
|
||||
Repo.insert_all(
|
||||
Endgame,
|
||||
[
|
||||
endgames = [
|
||||
%{
|
||||
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
|
||||
result: :win
|
||||
},
|
||||
%{
|
||||
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
|
||||
result: :win
|
||||
}
|
||||
],
|
||||
]
|
||||
|
||||
Repo.insert_all(
|
||||
Endgame,
|
||||
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
|
||||
)
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
@@ -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")
|
||||
|
||||
@@ -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")
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user