Instance Extension transformers — bake DSL data at compile time

matt-beanland · matt-beanland · commit dc26701e747b · 2026-04-28T10:02:05.000+09:30
Five Spark.Dsl.Transformer modules bake structural DSL data into zero-cost
module functions (__diffo_specification__/0, __diffo_characteristics__/0,
__diffo_features__/0, __diffo_party_declarations__/0) and a behavioural
transformer (TransformBuildActions) composes them into __diffo_build_before__/1
and __diffo_build_after__/2.

2-arity variants added to Specification, Feature, Characteristic, and Party
helpers accept pre-baked declaration lists instead of doing runtime Info
introspection, so the generated build hooks pay no Info lookup cost at runtime.

Transformer ordering is enforced via after?/1 so TransformBuildActions always
runs after all four structural transformers.
diff --git a/lib/diffo/provider/components/instance/extension.ex b/lib/diffo/provider/components/instance/extension.ex
@@ -224,6 +224,13 @@ defmodule Diffo.Provider.Instance.Extension do
 
   use Spark.Dsl.Extension,
     sections: [@specification, @features, @characteristics, @parties],
+    transformers: [
+      Diffo.Provider.Instance.Extension.Transformers.TransformSpecification,
+      Diffo.Provider.Instance.Extension.Transformers.TransformCharacteristics,
+      Diffo.Provider.Instance.Extension.Transformers.TransformFeatures,
+      Diffo.Provider.Instance.Extension.Transformers.TransformParties,
+      Diffo.Provider.Instance.Extension.Transformers.TransformBuildActions
+    ],
     verifiers: [
       Diffo.Provider.Instance.Extension.Verifiers.VerifySpecification,
       Diffo.Provider.Instance.Extension.Verifiers.VerifyCharacteristics,
diff --git a/lib/diffo/provider/components/instance/extension/characteristic.ex b/lib/diffo/provider/components/instance/extension/characteristic.ex
@@ -35,13 +35,30 @@ defmodule Diffo.Provider.Instance.Characteristic do
     end
   end
 
+  def set_characteristics_argument(changeset, declarations)
+      when is_struct(changeset, Ash.Changeset) and is_list(declarations) do
+    case characteristics = create_characteristics_from_declarations(declarations, :instance) do
+      [] ->
+        changeset
+
+      {:error, error} ->
+        Ash.Changeset.add_error(changeset, error)
+
+      _ ->
+        characteristic_ids = Enum.map(characteristics, &Map.get(&1, :id))
+        Ash.Changeset.force_set_argument(changeset, :characteristics, characteristic_ids)
+    end
+  end
+
   @doc """
   Creates the Characteristics from a Extended Instance's module
   """
   def create_characteristics(module, type) when is_atom(module) and is_atom(type) do
-    characteristics = Info.characteristics(module)
+    Info.characteristics(module) |> create_characteristics_from_declarations(type)
+  end
 
-    Enum.reduce_while(characteristics, [], fn %{name: name, value_type: value_type}, acc ->
+  defp create_characteristics_from_declarations(declarations, type) do
+    Enum.reduce_while(declarations, [], fn %{name: name, value_type: value_type}, acc ->
       try do
         attrs =
           case value_type do
diff --git a/lib/diffo/provider/components/instance/extension/feature.ex b/lib/diffo/provider/components/instance/extension/feature.ex
@@ -35,14 +35,31 @@ defmodule Diffo.Provider.Instance.Feature do
     end
   end
 
+  def set_features_argument(changeset, declarations)
+      when is_struct(changeset, Ash.Changeset) and is_list(declarations) do
+    case features = create_features_from_declarations(declarations) do
+      [] ->
+        changeset
+
+      {:error, error} ->
+        Ash.Changeset.add_error(changeset, error)
+
+      _ ->
+        feature_ids = Enum.map(features, &Map.get(&1, :id))
+        Ash.Changeset.force_set_argument(changeset, :features, feature_ids)
+    end
+  end
+
   @doc """
   Creates the Features from a Extended Instance's module
   """
   def create_features(module) when is_atom(module) do
-    features = Info.features(module)
+    Info.features(module) |> create_features_from_declarations()
+  end
 
+  defp create_features_from_declarations(declarations) do
     Enum.reduce_while(
-      features,
+      declarations,
       [],
       # create any feature characteristics
       fn %{name: name, is_enabled?: isEnabled, characteristics: characteristics}, acc ->
diff --git a/lib/diffo/provider/components/instance/extension/party.ex b/lib/diffo/provider/components/instance/extension/party.ex
@@ -15,7 +15,10 @@ defmodule Diffo.Provider.Instance.Party do
   @doc false
   def validate_parties(changeset) do
     declarations = InstanceInfo.parties(changeset.resource)
+    validate_parties(changeset, declarations)
+  end
 
+  def validate_parties(changeset, declarations) do
     if declarations == [] do
       changeset
     else
diff --git a/lib/diffo/provider/components/instance/extension/specification.ex b/lib/diffo/provider/components/instance/extension/specification.ex
@@ -30,6 +30,19 @@ defmodule Diffo.Provider.Instance.Specification do
     end
   end
 
+  def set_specified_by_argument(changeset, options)
+      when is_struct(changeset, Ash.Changeset) and is_list(options) do
+    specification = struct(__MODULE__, options)
+
+    case Provider.create_specification(Map.from_struct(specification)) do
+      {:ok, _} ->
+        Ash.Changeset.force_set_argument(changeset, :specified_by, specification.id)
+
+      {:error, error} ->
+        Ash.Changeset.add_error(changeset, error)
+    end
+  end
+
   @doc """
   Upserts the Specification from a Extended Instance's module
   """
diff --git a/lib/diffo/provider/components/instance/extension/transformers/transform_build_actions.ex b/lib/diffo/provider/components/instance/extension/transformers/transform_build_actions.ex
@@ -0,0 +1,35 @@
+# SPDX-FileCopyrightText: 2025 diffo contributors <https://github.com/diffo-dev/diffo/graphs.contributors>
+#
+# SPDX-License-Identifier: MIT
+
+defmodule Diffo.Provider.Instance.Extension.Transformers.TransformBuildActions do
+  @moduledoc "Generates __diffo_build_before__/1 and __diffo_build_after__/2 from baked structural data"
+  use Spark.Dsl.Transformer
+  alias Spark.Dsl.Transformer
+
+  @impl true
+  def transform(dsl_state) do
+    {:ok, Transformer.eval(dsl_state, [], quote do
+      @doc false
+      def __diffo_build_before__(changeset) do
+        changeset
+        |> Diffo.Provider.Instance.Specification.set_specified_by_argument(__diffo_specification__())
+        |> Diffo.Provider.Instance.Feature.set_features_argument(__diffo_features__())
+        |> Diffo.Provider.Instance.Characteristic.set_characteristics_argument(__diffo_characteristics__())
+        |> Diffo.Provider.Instance.Party.validate_parties(__diffo_party_declarations__())
+      end
+
+      @doc false
+      def __diffo_build_after__(changeset, result) do
+        Diffo.Provider.Instance.ActionHelper.build_after(changeset, result)
+      end
+    end)}
+  end
+
+  @impl true
+  def after?(Diffo.Provider.Instance.Extension.Transformers.TransformSpecification), do: true
+  def after?(Diffo.Provider.Instance.Extension.Transformers.TransformCharacteristics), do: true
+  def after?(Diffo.Provider.Instance.Extension.Transformers.TransformFeatures), do: true
+  def after?(Diffo.Provider.Instance.Extension.Transformers.TransformParties), do: true
+  def after?(_), do: false
+end
diff --git a/lib/diffo/provider/components/instance/extension/transformers/transform_characteristics.ex b/lib/diffo/provider/components/instance/extension/transformers/transform_characteristics.ex
@@ -0,0 +1,20 @@
+# SPDX-FileCopyrightText: 2025 diffo contributors <https://github.com/diffo-dev/diffo/graphs.contributors>
+#
+# SPDX-License-Identifier: MIT
+
+defmodule Diffo.Provider.Instance.Extension.Transformers.TransformCharacteristics do
+  @moduledoc "Bakes characteristic declarations into __diffo_characteristics__/0"
+  use Spark.Dsl.Transformer
+  alias Spark.Dsl.Transformer
+
+  @impl true
+  def transform(dsl_state) do
+    characteristics = Transformer.get_entities(dsl_state, [:characteristics])
+    escaped = Macro.escape(characteristics)
+
+    {:ok, Transformer.eval(dsl_state, [], quote do
+      @doc false
+      def __diffo_characteristics__, do: unquote(escaped)
+    end)}
+  end
+end
diff --git a/lib/diffo/provider/components/instance/extension/transformers/transform_features.ex b/lib/diffo/provider/components/instance/extension/transformers/transform_features.ex
@@ -0,0 +1,20 @@
+# SPDX-FileCopyrightText: 2025 diffo contributors <https://github.com/diffo-dev/diffo/graphs.contributors>
+#
+# SPDX-License-Identifier: MIT
+
+defmodule Diffo.Provider.Instance.Extension.Transformers.TransformFeatures do
+  @moduledoc "Bakes feature declarations into __diffo_features__/0"
+  use Spark.Dsl.Transformer
+  alias Spark.Dsl.Transformer
+
+  @impl true
+  def transform(dsl_state) do
+    features = Transformer.get_entities(dsl_state, [:features])
+    escaped = Macro.escape(features)
+
+    {:ok, Transformer.eval(dsl_state, [], quote do
+      @doc false
+      def __diffo_features__, do: unquote(escaped)
+    end)}
+  end
+end
diff --git a/lib/diffo/provider/components/instance/extension/transformers/transform_parties.ex b/lib/diffo/provider/components/instance/extension/transformers/transform_parties.ex
@@ -0,0 +1,20 @@
+# SPDX-FileCopyrightText: 2025 diffo contributors <https://github.com/diffo-dev/diffo/graphs.contributors>
+#
+# SPDX-License-Identifier: MIT
+
+defmodule Diffo.Provider.Instance.Extension.Transformers.TransformParties do
+  @moduledoc "Bakes party declarations into __diffo_party_declarations__/0"
+  use Spark.Dsl.Transformer
+  alias Spark.Dsl.Transformer
+
+  @impl true
+  def transform(dsl_state) do
+    parties = Transformer.get_entities(dsl_state, [:parties])
+    escaped = Macro.escape(parties)
+
+    {:ok, Transformer.eval(dsl_state, [], quote do
+      @doc false
+      def __diffo_party_declarations__, do: unquote(escaped)
+    end)}
+  end
+end
diff --git a/lib/diffo/provider/components/instance/extension/transformers/transform_specification.ex b/lib/diffo/provider/components/instance/extension/transformers/transform_specification.ex
@@ -0,0 +1,28 @@
+# SPDX-FileCopyrightText: 2025 diffo contributors <https://github.com/diffo-dev/diffo/graphs.contributors>
+#
+# SPDX-License-Identifier: MIT
+
+defmodule Diffo.Provider.Instance.Extension.Transformers.TransformSpecification do
+  @moduledoc "Bakes specification DSL options into __diffo_specification__/0"
+  use Spark.Dsl.Transformer
+  alias Spark.Dsl.Transformer
+
+  @impl true
+  def transform(dsl_state) do
+    spec = [
+      id: Transformer.get_option(dsl_state, [:specification], :id),
+      name: Transformer.get_option(dsl_state, [:specification], :name),
+      type: Transformer.get_option(dsl_state, [:specification], :type),
+      major_version: Transformer.get_option(dsl_state, [:specification], :major_version),
+      description: Transformer.get_option(dsl_state, [:specification], :description),
+      category: Transformer.get_option(dsl_state, [:specification], :category)
+    ]
+
+    escaped = Macro.escape(spec)
+
+    {:ok, Transformer.eval(dsl_state, [], quote do
+      @doc false
+      def __diffo_specification__, do: unquote(escaped)
+    end)}
+  end
+end
diff --git a/test/instance_extension/transformer_test.exs b/test/instance_extension/transformer_test.exs
@@ -0,0 +1,139 @@
+# SPDX-FileCopyrightText: 2025 diffo contributors <https://github.com/diffo-dev/diffo/graphs.contributors>
+#
+# SPDX-License-Identifier: MIT
+
+defmodule Diffo.InstanceExtension.TransformerTest do
+  @moduledoc false
+  use ExUnit.Case, async: true
+
+  alias Diffo.Test.Shelf
+  alias Diffo.Test.Card
+  alias Diffo.Provider.Instance.Characteristic
+  alias Diffo.Provider.Instance.Feature
+
+  describe "TransformSpecification" do
+    test "bakes specification options into __diffo_specification__/0" do
+      spec = Shelf.__diffo_specification__()
+      assert spec[:id] == "ef016d85-9dbd-429c-84da-1df56cc7dda5"
+      assert spec[:name] == "shelf"
+      assert spec[:type] == :resourceSpecification
+      assert spec[:description] == "A Shelf Resource Instance which contain cards"
+      assert spec[:category] == "Network Resource"
+    end
+
+    test "card specification is also baked correctly" do
+      spec = Card.__diffo_specification__()
+      assert spec[:id] == "cd29956f-6c68-44cc-bf54-705eb8d2f754"
+      assert spec[:name] == "card"
+      assert spec[:type] == :resourceSpecification
+    end
+  end
+
+  describe "TransformCharacteristics" do
+    test "bakes characteristic declarations into __diffo_characteristics__/0" do
+      chars = Shelf.__diffo_characteristics__()
+      assert is_list(chars)
+      assert length(chars) == 3
+      names = Enum.map(chars, & &1.name)
+      assert :shelf in names
+      assert :slots in names
+      assert :shelves in names
+    end
+
+    test "each characteristic is a Characteristic struct" do
+      [first | _] = Shelf.__diffo_characteristics__()
+      assert is_struct(first, Characteristic)
+    end
+
+    test "card characteristics are baked" do
+      chars = Card.__diffo_characteristics__()
+      assert length(chars) == 2
+      names = Enum.map(chars, & &1.name)
+      assert :card in names
+      assert :ports in names
+    end
+  end
+
+  describe "TransformFeatures" do
+    test "bakes feature declarations into __diffo_features__/0" do
+      features = Shelf.__diffo_features__()
+      assert is_list(features)
+      assert length(features) == 1
+      [feature] = features
+      assert feature.name == :spectralManagement
+      assert feature.is_enabled? == true
+    end
+
+    test "each feature is a Feature struct" do
+      [feature] = Shelf.__diffo_features__()
+      assert is_struct(feature, Feature)
+    end
+
+    test "feature characteristics are nested in the feature declaration" do
+      [feature] = Shelf.__diffo_features__()
+      assert length(feature.characteristics) == 2
+      char_names = Enum.map(feature.characteristics, & &1.name)
+      assert :deploymentClass in char_names
+      assert :deploymentClasses in char_names
+    end
+
+    test "card has no features" do
+      assert Card.__diffo_features__() == []
+    end
+  end
+
+  describe "TransformParties" do
+    test "bakes party declarations into __diffo_party_declarations__/0" do
+      parties = Shelf.__diffo_party_declarations__()
+      assert is_list(parties)
+      assert length(parties) == 5
+      roles = Enum.map(parties, & &1.role)
+      assert :facilitator in roles
+      assert :overseer in roles
+      assert :provider in roles
+      assert :manager in roles
+      assert :installer in roles
+    end
+
+    test "reference party has reference flag set" do
+      parties = Shelf.__diffo_party_declarations__()
+      provider = Enum.find(parties, &(&1.role == :provider))
+      assert provider.reference == true
+    end
+
+    test "calculate party has calculate set" do
+      parties = Shelf.__diffo_party_declarations__()
+      manager = Enum.find(parties, &(&1.role == :manager))
+      assert manager.calculate == :manager_calc
+    end
+
+    test "plural party has constraints" do
+      parties = Shelf.__diffo_party_declarations__()
+      installer = Enum.find(parties, &(&1.role == :installer))
+      assert installer.multiple == true
+      assert installer.constraints == [min: 1, max: 3]
+    end
+
+    test "card has no parties" do
+      assert Card.__diffo_party_declarations__() == []
+    end
+  end
+
+  describe "TransformBuildActions" do
+    test "__diffo_build_before__/1 is defined on shelf" do
+      assert function_exported?(Shelf, :__diffo_build_before__, 1)
+    end
+
+    test "__diffo_build_after__/2 is defined on shelf" do
+      assert function_exported?(Shelf, :__diffo_build_after__, 2)
+    end
+
+    test "__diffo_build_before__/1 is defined on card" do
+      assert function_exported?(Card, :__diffo_build_before__, 1)
+    end
+
+    test "__diffo_build_after__/2 is defined on card" do
+      assert function_exported?(Card, :__diffo_build_after__, 2)
+    end
+  end
+end
