Files
chess-endgame-trainer/lib/chesstrainer/themes.ex
T
owenrees 80cb033077 Add theme slugs, kinds and link provenance (#192)
* add function for upgrading a user's plan in interactive Elixir

* Add theme slugs, kinds and link provenance

Themes gain a stable slug, an optional description and a kind so the app can
tell material, motif and technique labels apart. Slugs are generated from the
name on first save and keep their value when the theme is renamed, so links to
a theme stay valid.

Endgame-to-theme links now record their source (derived, curated or community)
and creation time. Existing links are backfilled as curated. A derived pass can
therefore replace only its own links, leaving human work untouched.

The admin index shows each theme's kind and its coverage across the library.
Creating a theme name requires the manage_themes capability, and members get an
unauthorized error instead, ahead of the suggestion flow.

Closes #185
2026-11-17 20:46:43 +01:00

287 lines
6.4 KiB
Elixir

defmodule Chesstrainer.Themes do
@moduledoc """
The Themes context.
"""
import Ecto.Query, warn: false
alias Chesstrainer.Accounts.Policy
alias Chesstrainer.Accounts.Scope
alias Chesstrainer.Repo
alias Chesstrainer.Themes.Theme
@doc """
Returns the list of themes.
## Examples
iex> list_themes()
[%Theme{}, ...]
"""
def list_themes do
Repo.all(Theme)
end
@doc """
Lists themes for the admin index with their endgame usage count.
Options:
* `:search` - case-insensitive match on the theme name
* `:category` - one of `:endgame`, `:opening`, `:tactic`, or blank for all
Returns `{theme, usage_count}` tuples sorted by name.
"""
def list_themes_for_admin(opts \\ []) do
search = opts |> Keyword.get(:search, "") |> to_string() |> String.trim()
category = normalize_category(Keyword.get(opts, :category, ""))
query = from(t in Theme, order_by: [asc: t.name])
query =
if search == "" do
query
else
where(query, [t], ilike(t.name, ^"%#{search}%"))
end
query =
if category do
where(query, [t], t.category == ^category)
else
query
end
query
|> join(:left, [t], j in "endgames_themes", on: j.theme_id == t.id)
|> group_by([t], t.id)
|> select([t, j], {t, count(j.endgame_id)})
|> Repo.all()
end
@doc """
Gets a single theme.
Raises `Ecto.NoResultsError` if the Theme does not exist.
## Examples
iex> get_theme!(123)
%Theme{}
iex> get_theme!(456)
** (Ecto.NoResultsError)
"""
def get_theme!(id), do: Repo.get!(Theme, id)
@doc """
Gets a single endgame theme by its slug.
Returns `nil` when no endgame theme has that slug.
"""
def get_theme_by_slug(slug) when is_binary(slug) do
Repo.one(
from t in Theme,
where: t.slug == ^slug and t.category == :endgame,
limit: 1
)
end
@doc """
Creates a theme.
This is the unscoped path used by internal callers such as seeds, fixtures and
the admin picker, which are already behind an authorization check. Prefer
`create_theme/2` wherever a scope is available.
## Examples
iex> create_theme(%{field: value})
{:ok, %Theme{}}
iex> create_theme(%{field: bad_value})
{:error, %Ecto.Changeset{}}
"""
def create_theme(attrs) do
%Theme{}
|> Theme.changeset(attrs)
|> Repo.insert()
end
@doc """
Creates a theme on behalf of an administrator.
Members cannot introduce new theme names; their contribution path is a
suggestion, which a moderator reviews. Returns `{:error, :unauthorized}`
for a scope that cannot manage themes.
"""
def create_theme(%Scope{} = scope, attrs) do
if Policy.can?(scope, :manage_themes) do
create_theme(attrs)
else
{:error, :unauthorized}
end
end
@doc """
Updates a theme.
## Examples
iex> update_theme(theme, %{field: new_value})
{:ok, %Theme{}}
iex> update_theme(theme, %{field: bad_value})
{:error, %Ecto.Changeset{}}
"""
def update_theme(%Theme{} = theme, attrs) do
theme
|> Theme.changeset(attrs)
|> Repo.update()
end
@doc """
Deletes a theme.
## Examples
iex> delete_theme(theme)
{:ok, %Theme{}}
iex> delete_theme(theme)
{:error, %Ecto.Changeset{}}
"""
def delete_theme(%Theme{} = theme) do
Repo.delete(theme)
end
@doc """
Returns an `%Ecto.Changeset{}` for tracking theme changes.
## Examples
iex> change_theme(theme)
%Ecto.Changeset{data: %Theme{}}
"""
def change_theme(%Theme{} = theme, attrs \\ %{}) do
Theme.changeset(theme, attrs)
end
def search("", _category), do: []
def search(query, category) when is_binary(query) do
case String.trim(query) do
"" ->
[]
query ->
pattern = "%#{query}%"
Theme
|> where([t], ilike(t.name, ^pattern) and t.category == ^category)
|> order_by([t], asc: t.name)
|> limit(20)
|> Repo.all()
end
end
@doc """
Finds a theme by name (trimmed and case-insensitive) for a category, creating it
if it does not exist.
Options:
* `:kind` - the kind for a newly created theme; defaults to `:technique`
This is the picker's helper and is expected to run behind an admin check.
"""
def get_or_create(name, category, opts \\ []) when is_binary(name) do
name = String.trim(name)
if name == "" do
{:error, :blank_name}
else
case find_by_name(name, category) do
nil ->
create_theme(%{
name: name,
category: category,
kind: Keyword.get(opts, :kind, :technique)
})
theme ->
{:ok, theme}
end
end
end
@doc """
Replaces the derived theme links for one endgame.
Only links whose source is `derived` are removed, so curated and
community-approved links survive every derivation pass. Links that are
already present are left alone, which makes the operation idempotent.
"""
@spec sync_derived_themes(Ecto.UUID.t(), [term()]) :: :ok
def sync_derived_themes(endgame_id, theme_ids) do
now = DateTime.utc_now() |> DateTime.truncate(:second)
Repo.transaction(fn ->
Repo.delete_all(
from l in "endgames_themes",
where: l.endgame_id == type(^endgame_id, :binary_id) and l.source == "derived"
)
rows =
theme_ids
|> Enum.uniq()
|> Enum.map(fn theme_id ->
%{
endgame_id: Ecto.UUID.dump!(endgame_id),
theme_id: theme_id,
source: "derived",
inserted_at: now
}
end)
if rows != [] do
Repo.insert_all("endgames_themes", rows, on_conflict: :nothing)
end
end)
:ok
end
defp find_by_name(name, category) do
downcased = String.downcase(name)
Repo.one(
from t in Theme,
where: t.category == ^category and fragment("lower(?)", t.name) == ^downcased,
limit: 1
)
end
@doc """
Returns the names of the given themes, sorted.
"""
def names(themes) when is_list(themes) do
themes |> Enum.map(& &1.name) |> Enum.sort()
end
defp normalize_category(category) when category in [:endgame, :opening, :tactic],
do: category
defp normalize_category(category) when is_binary(category) do
Enum.find([:endgame, :opening, :tactic], &(Atom.to_string(&1) == category))
end
defp normalize_category(_category), do: nil
end