From ee246767ca84016ddbd0f3c694769510379503d0 Mon Sep 17 00:00:00 2001
From: Matt Enlow <matt@novaugust.net>
Date: Fri, 22 Nov 2024 18:34:28 -0700
Subject: [PATCH] ship it squirrel goes here

---
 CHANGELOG.md                           | 66 ++++++++++++++++++++++++++
 lib/style/comment_directives.ex        |  2 +-
 test/style/comment_directives_test.exs | 24 ++++++++++
 3 files changed, 91 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index e3cb4bc..e40e0c6 100644
--- a/CHANGELOG.md
+++ b/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
diff --git a/lib/style/comment_directives.ex b/lib/style/comment_directives.ex
index b0ba013..d41e088 100644
--- a/lib/style/comment_directives.ex
+++ b/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
diff --git a/test/style/comment_directives_test.exs b/test/style/comment_directives_test.exs
index 071a121..e5e95ec 100644
--- a/test/style/comment_directives_test.exs
+++ b/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