improvement: add singleton_entity_keys to sections

closes #245

Author: zachdaniel

lib/spark/dsl/extension.ex

@@ -439,7 +439,12 @@ defmodule Spark.Dsl.Extension do
       @doc false
       def sections, do: @_sections
       @doc false
-      def verifiers, do: [Spark.Dsl.Verifiers.VerifyEntityUniqueness | @_verifiers]
+      def verifiers,
+        do: [
+          Spark.Dsl.Verifiers.VerifyEntityUniqueness,
+          Spark.Dsl.Verifiers.VerifySectionSingletonEntities | @_verifiers
+        ]
+
       @doc false
       def persisters, do: @_persisters
       @doc false

lib/spark/dsl/section.ex

@@ -25,6 +25,9 @@ defmodule Spark.Dsl.Section do
   To create a section that is available at the top level (i.e not  nested inside of its own name), use
   `top_level?: true`. Remember, however, that this has no effect on sections nested inside of other sections.
 
+  `singleton_entity_keys` specifies a set of entity names (by their `:name` field) that should only
+  appear at most once within the section. This is validated automatically during compilation.
+
   For a full example, see `Spark.Dsl.Extension`.
   """
   defstruct [
@@ -40,6 +43,7 @@ defmodule Spark.Dsl.Section do
     top_level?: false,
     no_depend_modules: [],
     auto_set_fields: [],
+    singleton_entity_keys: [],
     deprecations: [],
     entities: [],
     sections: [],
@@ -111,6 +115,8 @@ defmodule Spark.Dsl.Section do
 
   @type auto_set_fields() :: keyword(any)
 
+  @type singleton_entity_keys :: [atom]
+
   @type entities :: [Entity.t()]
 
   @type sections :: [Section.t()]
@@ -134,6 +140,7 @@ defmodule Spark.Dsl.Section do
           modules: modules(),
           no_depend_modules: no_depend_modules(),
           auto_set_fields: auto_set_fields(),
+          singleton_entity_keys: singleton_entity_keys(),
           entities: entities(),
           sections: sections(),
           docs: docs(),

lib/spark/dsl/verifiers/verify_section_singleton_entities.ex

@@ -0,0 +1,68 @@
+# SPDX-FileCopyrightText: 2022 spark contributors <https://github.com/ash-project/spark/graphs/contributors>
+#
+# SPDX-License-Identifier: MIT
+
+defmodule Spark.Dsl.Verifiers.VerifySectionSingletonEntities do
+  @moduledoc """
+  Verifies that entities specified in a section's `singleton_entity_keys`
+  appear at most once within that section.
+  """
+
+  use Spark.Dsl.Verifier
+
+  alias Spark.Dsl.Verifier
+
+  def verify(dsl_state) do
+    module = Verifier.get_persisted(dsl_state, :module)
+
+    dsl_state
+    |> Verifier.get_persisted(:extensions)
+    |> Enum.each(fn extension ->
+      Enum.each(extension.sections(), fn section ->
+        verify_section(module, section, dsl_state)
+      end)
+    end)
+
+    :ok
+  end
+
+  defp verify_section(module, section, dsl_state, path \\ []) do
+    section_path = path ++ [section.name]
+
+    case section.singleton_entity_keys do
+      [] ->
+        :ok
+
+      singleton_keys ->
+        entities = Verifier.get_entities(dsl_state, section_path)
+
+        Enum.each(singleton_keys, fn key ->
+          entity_def = Enum.find(section.entities, &(&1.name == key))
+
+          if entity_def do
+            matching =
+              Enum.filter(entities, &(&1.__struct__ == entity_def.target))
+
+            if length(matching) > 1 do
+              location =
+                case matching do
+                  [_, second | _] -> Spark.Dsl.Entity.anno(second)
+                  _ -> nil
+                end
+
+              raise Spark.Error.DslError,
+                module: module,
+                path: section_path,
+                message:
+                  "Expected at most one #{key} in #{inspect(section_path)}, got #{length(matching)}",
+                location: location
+            end
+          end
+        end)
+    end
+
+    Enum.each(section.sections, fn nested_section ->
+      verify_section(module, nested_section, dsl_state, section_path)
+    end)
+  end
+end

test/dsl_test.exs

@@ -364,6 +364,55 @@ defmodule Spark.DslTest do
         end
       end
     end
+
+    test "section singleton_entity_keys allows zero entities" do
+      defmodule SectionSingletonZero do
+        @moduledoc false
+        use Spark.Test.Contact
+
+        personal_details do
+          first_name("Zach")
+        end
+      end
+    end
+
+    test "section singleton_entity_keys allows one entity" do
+      defmodule SectionSingletonOne do
+        @moduledoc false
+        use Spark.Test.Contact
+
+        singleton_section do
+          singleton(:only_one)
+        end
+
+        personal_details do
+          first_name("Zach")
+        end
+      end
+
+      assert [%Spark.Test.Contact.Dsl.Singleton{value: :only_one}] =
+               Spark.Dsl.Extension.get_entities(SectionSingletonOne, [:singleton_section])
+    end
+
+    test "section singleton_entity_keys rejects multiple entities" do
+      import ExUnit.CaptureIO
+
+      assert capture_io(:stderr, fn ->
+               defmodule SectionSingletonMultiple do
+                 @moduledoc false
+                 use Spark.Test.Contact
+
+                 singleton_section do
+                   singleton(:first)
+                   singleton(:second)
+                 end
+
+                 personal_details do
+                   first_name("Zach")
+                 end
+               end
+             end) =~ "Expected at most one singleton"
+    end
   end
 
   describe "annotation tracking" do

test/support/contact/contact.ex

@@ -256,6 +256,12 @@ defmodule Spark.Test.Contact do
       ]
     }
 
+    @singleton_section %Spark.Dsl.Section{
+      name: :singleton_section,
+      entities: [@singleton],
+      singleton_entity_keys: [:singleton]
+    }
+
     @awesome_status %Spark.Dsl.Section{
       name: :awesome?,
       schema: [
@@ -276,7 +282,14 @@ defmodule Spark.Test.Contact do
     end
 
     use Spark.Dsl.Extension,
-      sections: [@contact, @personal_details, @address, @presets, @awesome_status],
+      sections: [
+        @contact,
+        @personal_details,
+        @address,
+        @presets,
+        @singleton_section,
+        @awesome_status
+      ],
       verifiers: [Spark.Test.Contact.Verifiers.VerifyNotGandalf],
       transformers: [Transformer]