chore: Miscellaneous clarifications and cleaning up (#8)

lib/code/common.ex

@@ -28,6 +28,17 @@ defmodule Igniter.Code.Common do
 
   @doc """
   Returns `true` if the current node matches the given pattern.
+
+  ## Examples:
+
+  ```elixir
+  list_zipper =
+    "[1, 2, 3]"
+    |> Sourceror.parse_string!()
+    |> Sourceror.Zipper.zip()
+
+  Common.node_matches_pattern?(list_zipper, value when is_list(value)) # true
+  ```
   """
   defmacro node_matches_pattern?(zipper, pattern) do
     quote do
@@ -62,22 +73,22 @@ defmodule Igniter.Code.Common do
   @doc """
   Adds the provided code to the zipper.
 
-  Use the `placement` to determine if the code goes `:after` or `:before` the current node.
+  Use `placement` to determine if the code goes `:after` or `:before` the current node.
 
   ## Example:
 
   ```elixir
-  existing_code = \"\"\"
+  existing_zipper = \"\"\"
   IO.inspect("Hello, world!")
   \"\"\"
   |> Sourceror.parse_string!()
+  |> Sourceror.Zipper.zip()
 
   new_code = \"\"\"
   IO.inspect("Goodbye, world!")
   \"\"\"
 
-  existing_code
+  existing_zipper
-  |> Sourceror.Zipper.zip()
   |> Igniter.Common.add_code(new_code)
   |> Sourceror.Zipper.root()
   |> Sourceror.to_string()
@@ -88,7 +99,7 @@ defmodule Igniter.Code.Common do
   ```elixir
   \"\"\"
   IO.inspect("Hello, world!")
-  |> Sourceror.to_string()
+  IO.inspect("Goodbye, world!") 
   \"\"\"
   ```
   """
@@ -180,8 +191,7 @@ defmodule Igniter.Code.Common do
 
       upwards ->
         upwards
-        |> Zipper.subtree()
+        |> Zipper.node()
-        |> Zipper.root()
         |> case do
           {:__block__, _, _} ->
             case highest_adjacent_block(upwards) do
@@ -530,20 +540,24 @@ defmodule Igniter.Code.Common do
     end
   end
 
+  @doc """
+  Expands the environment at the current zipper position and returns the
+  expanded environment. Currently used for properly working with aliases.
+  """
   def env_at_cursor(zipper) do
     zipper
     |> do_add_code({:__cursor__, [], []}, :after, false)
-    |> Zipper.topmost()
+    |> Zipper.topmost_root()
-    |> Zipper.node()
     |> Sourceror.to_string()
     |> String.split("__cursor__()", parts: 2)
-    |> Enum.at(0)
+    |> List.first()
     |> Spitfire.container_cursor_to_quoted()
-    |> elem(1)
+    |> then(fn {:ok, ast} ->
+      ast
+    end)
     |> Spitfire.Env.expand("file.ex")
-    |> elem(3)
+    |> then(fn {_ast, _final_state, _final_env, cursor_env} ->
-    |> then(fn value ->
+      {:ok, struct(Macro.Env, cursor_env)}
-      {:ok, struct(Macro.Env, value)}
     end)
   rescue
     _e ->

lib/code/list.ex

@@ -15,7 +15,7 @@ defmodule Igniter.Code.List do
     Common.node_matches_pattern?(zipper, value when is_list(value))
   end
 
-  @doc "Prepends `quoted` to the list unless it is alread present, determined by `equality_pred`."
+  @doc "Prepends `quoted` to the list unless it is already present, determined by `equality_pred`."
   @spec prepend_new_to_list(Zipper.t(), quoted :: Macro.t(), equality_pred) ::
           {:ok, Zipper.t()} | :error
   def prepend_new_to_list(zipper, quoted, equality_pred \\ &Common.nodes_equal?/2) do
@@ -36,7 +36,7 @@ defmodule Igniter.Code.List do
     end
   end
 
-  @doc "Appends `quoted` to the list unless it is alread present, determined by `equality_pred`."
+  @doc "Appends `quoted` to the list unless it is already present, determined by `equality_pred`."
   @spec append_new_to_list(Zipper.t(), quoted :: Macro.t(), equality_pred) ::
           {:ok, Zipper.t()} | :error
   def append_new_to_list(zipper, quoted, equality_pred \\ &Common.nodes_equal?/2) do

lib/igniter.ex

@@ -61,11 +61,16 @@ defmodule Igniter do
   """
   @spec update_glob(
           t,
-          Path.t(),
+          Path.t() | GlobEx.t(),
           zipper_updater
         ) :: t()
   def update_glob(igniter, glob, func) do
-    glob = GlobEx.compile!(glob)
+    glob =
+      case glob do
+        %GlobEx{} = glob -> glob
+        string -> GlobEx.compile!(string)
+      end
+
     igniter = include_glob(igniter, glob)
 
     Enum.reduce(igniter.rewrite, igniter, fn source, igniter ->
@@ -157,9 +162,9 @@ defmodule Igniter do
   Updates a given file's `Rewrite.Source`
   """
   @spec update_file(t(), Path.t(), (Rewrite.Source.t() -> Rewrite.Source.t())) :: t()
-  def update_file(igniter, path, func) do
+  def update_file(igniter, path, updater) do
     if Rewrite.has_source?(igniter.rewrite, path) do
-      %{igniter | rewrite: Rewrite.update!(igniter.rewrite, path, func)}
+      %{igniter | rewrite: Rewrite.update!(igniter.rewrite, path, updater)}
     else
       if File.exists?(path) do
         source = Rewrite.Source.Ex.read!(path)
@@ -168,7 +173,7 @@ defmodule Igniter do
         |> format(path)
         |> Map.update!(:rewrite, fn rewrite ->
           source = Rewrite.source!(rewrite, path)
-          Rewrite.update!(rewrite, path, func.(source))
+          Rewrite.update!(rewrite, path, updater.(source))
         end)
       else
         add_issue(igniter, "Required #{path} but it did not exist")
@@ -217,12 +222,12 @@ defmodule Igniter do
     Rewrite.has_source?(igniter.rewrite, path) || File.exists?(path)
   end
 
-  @doc "Updates or creates the given file in the project with the provided contents."
+  @doc "Creates the given file in the project with the provided string contents, or updates it with a function of type `zipper_updater()` if it already exists."
   @spec create_or_update_elixir_file(t(), Path.t(), String.t(), zipper_updater()) :: Igniter.t()
-  def create_or_update_elixir_file(igniter, path, contents, func) do
+  def create_or_update_elixir_file(igniter, path, contents, updater) do
     if Rewrite.has_source?(igniter.rewrite, path) do
       igniter
-      |> update_elixir_file(path, func)
+      |> update_elixir_file(path, updater)
     else
       {created?, source} =
         try do
@@ -241,13 +246,13 @@ defmodule Igniter do
         if created? do
           igniter
         else
-          update_elixir_file(igniter, path, func)
+          update_elixir_file(igniter, path, updater)
         end
       end)
     end
   end
 
-  @doc "Creates a new elixir file in the project with the provided contents. Adds an error if it already exists."
+  @doc "Creates a new elixir file in the project with the provided string contents. Adds an error if it already exists."
   @spec create_new_elixir_file(t(), Path.t(), String.t()) :: Igniter.t()
   def create_new_elixir_file(igniter, path, contents \\ "") do
     source =