ship it squirrel goes here

CHANGELOG.md

@@ -4,6 +4,72 @@
 they can and will change without that change being reflected in Styler's semantic version.
 ## main
 
+### Improvements
+
+#### `# styler:sort` Styler's first comment directive
+
+Styler will now keep a user-designated list or wordlist (`~w` sigil) sorted as part of formatting via the use of comments.
+
+The intention is to remove comments to humans, like `# Please keep this list sorted!`, in favor of comments to robots: `# styler:sort`. Personally speaking, Styler is much better at alphabetical-order than I ever will be.
+
+To use the new directive, put it on the line before a list or wordlist.
+
+This example:
+
+```elixir
+# styler:sort
+[:c, :a, :b]
+
+# styler:sort
+~w(a list of words)
+
+# styler:sort
+@country_codes ~w(
+  en_US
+  po_PO
+  fr_CA
+  ja_JP
+)
+
+# styler:sort
+a_var =
+  [
+    Modules,
+    In,
+    A,
+    List
+  ]
+```
+
+Would yield:
+
+```elixir
+# styler:sort
+[:a, :b, :c]
+
+# styler:sort
+~w(a list of words)
+
+# styler:sort
+@country_codes ~w(
+  en_US
+  fr_CA
+  ja_JP
+  po_PO
+)
+
+# styler:sort
+a_var =
+  [
+    A,
+    In,
+    List,
+    Modules
+  ]
+```
+
+Sorting is done according to erlang term ordering, so lists with elements of multiple types will work just fine.
+
 ## 1.2.1
 
 ### Fixes

lib/style/comment_directives.ex

@@ -34,7 +34,7 @@ defmodule Styler.Style.CommentDirectives do
         end
       end)
 
-    {:skip, zipper, ctx}
+    {:halt, zipper, ctx}
   end
 
   defp sort({:__block__, meta, [list]}) when is_list(list) do

test/style/comment_directives_test.exs

@@ -126,5 +126,29 @@ defmodule Styler.Style.CommentDirectivesTest do
         """
       )
     end
+
+    test "doesnt affect downstream nodes" do
+      assert_style """
+      # styler:sort
+      [:c, :a, :b]
+
+      @country_codes ~w(
+        po_PO
+        en_US
+        fr_CA
+        ja_JP
+      )
+      """, """
+      # styler:sort
+      [:a, :b, :c]
+
+      @country_codes ~w(
+        po_PO
+        en_US
+        fr_CA
+        ja_JP
+      )
+      """
+    end
   end
 end