improvement: add Igniter.Code.Common.add_comment/2

zachdaniel · zachdaniel · commit 580d1bf3fc27 · 2025-03-21T23:35:57.000-04:00
Comments are important and now there is a higher level function for
adding them.

improvement: add `Igniter.Project.Config.configure_group/6`

`Igniter.Project.Config.configure_group/6` is an elegant way to
configure many things at once, with support for adding an explanatory
comment above the entire group. So on a fresh installation when there
is nothing for a given app/shared prefix configured, you get a config
like

```elixir
config :my_app, SomeModule,
  foo: :foo,
  bar: :bar
```

but if the shared prefix is configured, we simply merge into existing
config without adding a comment.
diff --git a/lib/igniter/code/common.ex b/lib/igniter/code/common.ex
@@ -247,6 +247,51 @@ defmodule Igniter.Code.Common do
     end
   end
 
+  def add_comment(zipper, comment, opts \\ []) do
+    zipper = maybe_move_to_single_child_block(zipper)
+
+    comments =
+      comment
+      |> String.trim_leading("\n")
+      |> String.trim_trailing("\n")
+      |> String.split("\n", trim: true)
+      |> Enum.map(fn
+        "" ->
+          "#"
+
+        string ->
+          if String.starts_with?(String.trim_leading(string), "#") do
+            string
+          else
+            if String.starts_with?(string, " ") do
+              "#" <> string
+            else
+              "# " <> string
+            end
+          end
+      end)
+      |> Enum.map(fn comment ->
+        %{
+          line: 0,
+          text: comment,
+          column: 0,
+          next_eol_count: 1,
+          previous_eol_count: 1
+        }
+      end)
+
+    node =
+      case opts[:placement] || :before do
+        :before ->
+          Sourceror.prepend_comments(zipper.node, comments)
+
+        :after ->
+          Sourceror.append_comments(zipper.node, comments)
+      end
+
+    Zipper.replace(zipper, node)
+  end
+
   @doc """
   Adds the provided code to the zipper.
 
@@ -304,6 +349,8 @@ defmodule Igniter.Code.Common do
     expand_env? = Keyword.get(opts, :expand_env?, true)
     placement = Keyword.get(opts, :placement, :after)
 
+    new_code = clean_lines(new_code)
+
     new_code =
       if expand_env? do
         use_aliases(new_code, zipper)
@@ -323,12 +370,12 @@ defmodule Igniter.Code.Common do
         {:__block__, upwards_meta, upwards_code} = upwards.node
         index = Enum.count(zipper.path.left || [])
 
-        {to_insert, new_meta} =
-          if extendable_block?(new_code) do
-            {:__block__, new_meta, new_code} = new_code
-            {new_code, new_meta}
+        to_insert =
+          if extendable_block?(new_code) and !has_comments?(new_code) do
+            {:__block__, _new_meta, new_code} = new_code
+            new_code
           else
-            {[new_code], []}
+            [new_code]
           end
 
         {head, tail} =
@@ -340,16 +387,15 @@ defmodule Igniter.Code.Common do
 
         Zipper.replace(
           upwards,
-          {:__block__, combine_comments(upwards_meta, new_meta, placement),
-           head ++ to_insert ++ tail}
+          {:__block__, upwards_meta, head ++ to_insert ++ tail}
         )
 
       super_upwards && extendable_block?(super_upwards.node) ->
         {:__block__, upwards_meta, upwards_code} = super_upwards.node
         index = Enum.count(zipper.supertree.path.left || [])
 
         {to_insert, new_meta} =
-          if extendable_block?(new_code) do
+          if extendable_block?(new_code) and !has_comments?(new_code) do
             {:__block__, new_meta, new_code} = new_code
             {new_code, new_meta}
           else
@@ -427,7 +473,7 @@ defmodule Igniter.Code.Common do
             Zipper.replace(zipper, {:__block__, meta, new_stuff})
           else
             {code, meta} =
-              if extendable_block?(new_code) do
+              if extendable_block?(new_code) and !has_comments?(new_code) do
                 {:__block__, meta, new_stuff} = new_code
 
                 if placement == :after do
@@ -449,6 +495,22 @@ defmodule Igniter.Code.Common do
     end
   end
 
+  defp clean_lines(ast) do
+    Macro.prewalk(ast, fn
+      {call, meta, args} ->
+        {call, Keyword.put(meta, :line, 0), args}
+
+      other ->
+        other
+    end)
+  end
+
+  defp has_comments?({_, meta, _}) do
+    List.wrap(meta[:leading_comments]) != [] || List.wrap(meta[:trailing_comments]) != []
+  end
+
+  defp has_comments?(_), do: false
+
   @doc """
   Updates all nodes matching the given predicate with the given function.
 
@@ -566,7 +628,10 @@ defmodule Igniter.Code.Common do
   end
 
   def replace_code(%Zipper{} = zipper, new_code) do
-    new_code = use_aliases(new_code, zipper)
+    new_code =
+      new_code
+      |> clean_lines()
+      |> use_aliases(zipper)
 
     if extendable_block?(new_code) and in_extendable_block?(zipper) do
       at_supertree_root? = Zipper.up(zipper) == nil and !!zipper.supertree
@@ -629,7 +694,6 @@ defmodule Igniter.Code.Common do
         new_meta[:trailing_comments] || [],
         &((new_meta[:trailing_comments] || []) ++ &1)
       )
-      |> ensure_unique_comments()
     else
       meta
       |> Keyword.update(
@@ -642,16 +706,9 @@ defmodule Igniter.Code.Common do
         new_meta[:trailing_comments] || [],
         &(&1 ++ (new_meta[:trailing_comments] || []))
       )
-      |> ensure_unique_comments()
     end
   end
 
-  defp ensure_unique_comments(meta) do
-    meta
-    |> Keyword.update!(:leading_comments, &Enum.uniq/1)
-    |> Keyword.update!(:trailing_comments, &Enum.uniq/1)
-  end
-
   defp multi_element_pipe?(%{node: {:|>, _, _}} = zipper) do
     up = Zipper.up(zipper)
     down = Zipper.down(zipper)
diff --git a/lib/igniter/project/config.ex b/lib/igniter/project/config.ex
@@ -8,6 +8,9 @@ defmodule Igniter.Project.Config do
   @type updater :: (Sourceror.Zipper.t() -> {:ok, Sourceror.Zipper.t()}) | :error | nil
   @type after_predicate :: (Sourceror.Zipper.t() -> boolean())
 
+  @type config_group_item ::
+          {list(term) | term(), term()} | {list(term) | term(), term(), Keyword.t()}
+
   @doc """
   Sets a config value in the given configuration file, if it is not already set.
 
@@ -31,6 +34,93 @@ defmodule Igniter.Project.Config do
     )
   end
 
+  @doc """
+  Configures a "group" of configurations, which is multiple configurations set at one time.
+  If the app + the shared prefix is already configured, then each configuration is added individually,
+  and the `comment` for the group is ignored. The sub configurations use `configure`, so if you want to
+  not change the value if its already set, use `updater: &{:ok, &1}` in the item opts.
+
+  ## Options
+
+  - `comment` - A comment string to add above the group when its added.
+  """
+  @spec configure_group(
+          Igniter.t(),
+          Path.t(),
+          atom(),
+          shared_prefix :: list(atom),
+          list(config_group_item()),
+          opts :: Keyword.t()
+        ) :: Igniter.t()
+  def configure_group(igniter, file_path, app_name, shared_prefix, items, opts \\ []) do
+    if Enum.empty?(items) do
+      raise ArgumentError, "Must provide at least one item in configure_group/6"
+    end
+
+    items =
+      Enum.map(items, fn
+        {sub_path, value} ->
+          {List.wrap(sub_path), value, opts}
+
+        {sub_path, value, opts} ->
+          {List.wrap(sub_path), value, opts}
+      end)
+
+    if configures_key?(igniter, file_path, app_name, shared_prefix) do
+      Enum.reduce(items, igniter, fn {path, value, opts}, igniter ->
+        configure(igniter, file_path, app_name, shared_prefix ++ path, value, opts)
+      end)
+    else
+      zipper =
+        {:__block__, [], []}
+        |> Zipper.zip()
+
+      code_with_configuration_added =
+        Enum.reduce(items, zipper, fn {path, value, opts}, zipper ->
+          modify_configuration_code(zipper, shared_prefix ++ path, app_name, value, opts)
+        end)
+        |> Zipper.topmost()
+        |> then(fn zipper ->
+          if opts[:comment] do
+            Igniter.Code.Common.add_comment(zipper, opts[:comment])
+          else
+            zipper
+          end
+        end)
+        |> Zipper.topmost_root()
+
+      config_file_path = config_file_path(igniter, file_path)
+
+      igniter
+      |> ensure_default_configs_exist()
+      |> Igniter.update_elixir_file(config_file_path, fn zipper ->
+        case Zipper.find(zipper, fn
+               {:import, _, [Config]} ->
+                 true
+
+               {:import, _, [{:__aliases__, _, [:Config]}]} ->
+                 true
+
+               _ ->
+                 false
+             end) do
+          nil ->
+            {:warning,
+             bad_config_message(
+               app_name,
+               file_path,
+               shared_prefix,
+               Sourceror.to_string(zipper),
+               opts
+             )}
+
+          zipper ->
+            Igniter.Code.Common.add_code(zipper, code_with_configuration_added)
+        end
+      end)
+    end
+  end
+
   @spec configure_runtime_env(
           Igniter.t(),
           atom(),
diff --git a/lib/igniter/util/debug.ex b/lib/igniter/util/debug.ex
@@ -19,7 +19,7 @@ defmodule Igniter.Util.Debug do
     :error
   end
 
-  def puts_code_at_node(zipper) do
+  def puts_code_at_node(%Zipper{} = zipper) do
     zipper
     |> Zipper.node()
     |> Sourceror.to_string()
@@ -29,6 +29,15 @@ defmodule Igniter.Util.Debug do
     zipper
   end
 
+  def puts_code_at_node(node) do
+    node
+    |> Sourceror.to_string()
+    |> then(&"==code==\n#{&1}\n==!code==\n")
+    |> IO.puts()
+
+    node
+  end
+
   @doc "Returns the formatted code at the node of the zipper to the console"
   def code_at_node(zipper) do
     zipper
@@ -37,7 +46,7 @@ defmodule Igniter.Util.Debug do
   end
 
   @doc "Puts the ast at the node of the zipper to the console"
-  def puts_ast_at_node(zipper) do
+  def puts_ast_at_node(%Zipper{} = zipper) do
     zipper
     |> Zipper.node()
     |> then(&"==ast==\n#{inspect(&1, pretty: true)}\n==!ast==\n")
diff --git a/mix.exs b/mix.exs
@@ -104,7 +104,7 @@ defmodule Igniter.MixProject do
       {:rewrite, "~> 1.1 and >= 1.1.1"},
       {:glob_ex, "~> 0.1.7"},
       {:spitfire, "~> 0.1 and >= 0.1.3"},
-      {:sourceror, "~> 1.4"},
+      {:sourceror, path: "../../oss/sourceror", override: true},
       {:jason, "~> 1.4"},
       {:req, "~> 0.5"},
       {:phx_new, "~> 1.7", optional: true},
diff --git a/test/igniter/project/config_test.exs b/test/igniter/project/config_test.exs
@@ -673,4 +673,51 @@ defmodule Igniter.Project.ConfigTest do
       assert String.contains?(config, "config :fake, foo: [bar: true]")
     end
   end
+
+  describe "configure_group" do
+    test "adds configuration with a comment above it" do
+      test_project()
+      |> Igniter.Project.Config.configure_group(
+        "config.exs",
+        :foo,
+        [:bar],
+        [
+          {:baz, :buz}
+        ],
+        comment: """
+          Configures the foobar to
+          accomplish the barbaz
+        """
+      )
+      |> assert_creates("config/config.exs", """
+      import Config
+      #  Configures the foobar to
+      #  accomplish the barbaz
+      config :foo, bar: [baz: :buz]
+      import_config "\#{config_env()}.exs"
+      """)
+    end
+
+    test "alters configuration without adding a comment if the group is already configured" do
+      test_project()
+      |> Igniter.Project.Config.configure("config.exs", :foo, [:bar], [])
+      |> apply_igniter!()
+      |> Igniter.Project.Config.configure_group(
+        "config.exs",
+        :foo,
+        [:bar],
+        [
+          {:baz, :buz}
+        ],
+        comment: """
+          Configures the foobar to
+          accomplish the barbaz
+        """
+      )
+      |> assert_has_patch("config/config.exs", """
+       - |config :foo, bar: []
+       + |config :foo, bar: [baz: :buz]
+      """)
+    end
+  end
 end
diff --git a/test/igniter/project/formatter_test.exs b/test/igniter/project/formatter_test.exs
@@ -40,7 +40,8 @@ defmodule Igniter.Project.FormatterTest do
         |  end
       + |
       + |  test "2" do
-      + |    expect Foo.subtract(x, y), do: x - y
+      + |    expect Foo.subtract(x, y), 
+      + |      do: x - y
       + |  end
         |end
       """)
diff --git a/test/igniter/project/test_test.exs b/test/igniter/project/test_test.exs
@@ -38,7 +38,11 @@ defmodule Igniter.Project.TestTest do
       assert String.contains?(
                contents,
                """
-               defp elixirc_paths(:test), do: elixirc_paths(:dev) ++ [\"test/support\"]\n  defp elixirc_paths(_), do: [\"lib\"]
+                 defp elixirc_paths(:test),
+                   do: elixirc_paths(:dev) ++ ["test/support"]
+
+                 defp elixirc_paths(_),
+                   do: ["lib"]
                """
                |> String.trim()
              )
diff --git a/test/igniter/refactors/elixir_test.exs b/test/igniter/refactors/elixir_test.exs
