fix: include documented mix tasks in public API snapshot

lib/mix/tasks/posthog.public_api.ex

@@ -3,9 +3,12 @@ defmodule Mix.Tasks.Posthog.PublicApi do
   Checks the committed public API snapshot.
 
   The snapshot is generated from compiled BEAM metadata. Public modules are
-  discovered from the current Mix application, `Code.fetch_docs/1` is used to
-  identify documented modules and function visibility, and `__info__/1` is used
-  to enumerate exported functions and macros.
+  discovered from the current Mix application. `PostHog.*` modules and
+  documented `Mix.Tasks.Posthog.*` modules are included. `Code.fetch_docs/1` is
+  used to identify documented modules and function visibility, and `__info__/1`
+  is used to enumerate exported functions and macros. Mix tasks also include
+  their task name, shortdoc, and module documentation text so command/options
+  documentation changes are checked.
 
       mix posthog.public_api --check
       mix posthog.public_api --update
@@ -56,7 +59,7 @@ defmodule Mix.Tasks.Posthog.PublicApi do
       "# This file is generated by `mix posthog.public_api --update`.",
       "# Do not edit manually.",
       "",
-      "# Public modules/functions/macros for #{Mix.Project.config()[:app]}",
+      "# Public modules/functions/macros and documented Mix tasks for #{Mix.Project.config()[:app]}",
       ""
       | Enum.flat_map(modules, &module_snapshot/1)
     ]
@@ -72,7 +75,7 @@ defmodule Mix.Tasks.Posthog.PublicApi do
     case :application.get_key(app, :modules) do
       {:ok, modules} ->
         modules
-        |> Enum.filter(&posthog_module?/1)
+        |> Enum.filter(&public_module?/1)
         |> Enum.reject(&hidden_module?/1)
         |> Enum.sort_by(&inspect/1)
 
@@ -81,12 +84,26 @@ defmodule Mix.Tasks.Posthog.PublicApi do
     end
   end
 
+  defp public_module?(module) do
+    posthog_module?(module) or documented_posthog_mix_task?(module)
+  end
+
   defp posthog_module?(module) do
     module
     |> Atom.to_string()
     |> String.starts_with?("Elixir.PostHog")
   end
 
+  defp documented_posthog_mix_task?(module) do
+    posthog_mix_task?(module) and documented_doc?(fetch_docs(module) |> elem(0))
+  end
+
+  defp posthog_mix_task?(module) do
+    module
+    |> Atom.to_string()
+    |> String.starts_with?("Elixir.Mix.Tasks.Posthog.")
+  end
+
   defp hidden_module?(module) do
     module
     |> fetch_docs()
@@ -101,9 +118,23 @@ defmodule Mix.Tasks.Posthog.PublicApi do
     [
       inspect(module),
       "  module_doc: #{doc_visibility(module_doc)}"
-      | exported_snapshot(module, :functions, :function, docs_by_id) ++
-          exported_snapshot(module, :macros, :macro, docs_by_id) ++ [""]
-    ]
+    ] ++
+      mix_task_snapshot(module, module_doc) ++
+      exported_snapshot(module, :functions, :function, docs_by_id) ++
+      exported_snapshot(module, :macros, :macro, docs_by_id) ++ [""]
+  end
+
+  defp mix_task_snapshot(module, module_doc) do
+    if posthog_mix_task?(module) do
+      [
+        "  mix_task: #{Mix.Task.task_name(module)}",
+        "  shortdoc: #{inspect(Mix.Task.shortdoc(module))}",
+        "  module_doc_text:"
+        | module_doc_text_lines(module_doc)
+      ]
+    else
+      []
+    end
   end
 
   defp exported_snapshot(module, info_key, kind, docs_by_id) do
@@ -143,10 +174,26 @@ defmodule Mix.Tasks.Posthog.PublicApi do
     end
   end
 
+  defp documented_doc?(:hidden), do: false
+  defp documented_doc?(:none), do: false
+  defp documented_doc?(_doc), do: true
+
   defp doc_visibility(:hidden), do: "hidden"
   defp doc_visibility(:none), do: "none"
   defp doc_visibility(_doc), do: "documented"
 
+  defp module_doc_text_lines(%{"en" => text}) do
+    text
+    |> String.trim_trailing()
+    |> String.split("\n")
+    |> Enum.map(fn
+      "" -> "    |"
+      line -> "    | #{line}"
+    end)
+  end
+
+  defp module_doc_text_lines(_module_doc), do: ["    (unavailable)"]
+
   defp write_snapshot(path, snapshot) do
     path
     |> Path.dirname()

public_api.snapshot

@@ -1,7 +1,74 @@
 # This file is generated by `mix posthog.public_api --update`.
 # Do not edit manually.
 
-# Public modules/functions/macros for posthog
+# Public modules/functions/macros and documented Mix tasks for posthog
+
+Mix.Tasks.Posthog.PackageSourceCode
+  module_doc: documented
+  mix_task: posthog.package_source_code
+  shortdoc: "Packages source code for PostHog error tracking source context"
+  module_doc_text:
+    | Packages source code into a binary file for source context in error tracking.
+    |
+    | This task reads all `.ex` source files from the configured root paths and
+    | writes a compressed binary into PostHog's own `priv/` directory. This file
+    | is then bundled into the release and loaded at runtime to provide source
+    | context in stack traces.
+    |
+    | Run this task before building a release:
+    |
+    |     mix posthog.package_source_code
+    |     mix release
+    |
+    | ## Options
+    |
+    |   * `--output` - Custom output path (default: PostHog's priv dir)
+    |   * `--root-path` - Root source code path(s). Can be specified multiple times.
+    |     Defaults to the current working directory.
+    |
+    | ## Configuration
+    |
+    | This task reads the following from your application config:
+    |
+    |     config :posthog,
+    |       root_source_code_paths: [File.cwd!()],
+    |       source_code_path_pattern: "**/*.ex",
+    |       source_code_exclude_patterns: [~r"^_build/", ~r"^priv/", ~r"^test/"]
+    |
+    | CLI options override config values.
+  functions:
+    (none)
+  macros:
+    (none)
+
+Mix.Tasks.Posthog.PublicApi
+  module_doc: documented
+  mix_task: posthog.public_api
+  shortdoc: "Checks the committed public API snapshot"
+  module_doc_text:
+    | Checks the committed public API snapshot.
+    |
+    | The snapshot is generated from compiled BEAM metadata. Public modules are
+    | discovered from the current Mix application. `PostHog.*` modules and
+    | documented `Mix.Tasks.Posthog.*` modules are included. `Code.fetch_docs/1` is
+    | used to identify documented modules and function visibility, and `__info__/1`
+    | is used to enumerate exported functions and macros. Mix tasks also include
+    | their task name, shortdoc, and module documentation text so command/options
+    | documentation changes are checked.
+    |
+    |     mix posthog.public_api --check
+    |     mix posthog.public_api --update
+    |
+    | ## Options
+    |
+    |   * `--check` - Compare the generated snapshot with the committed snapshot.
+    |     This is the default.
+    |   * `--update` - Regenerate the committed snapshot.
+    |   * `--snapshot` - Snapshot path. Defaults to `public_api.snapshot`.
+  functions:
+    (none)
+  macros:
+    (none)
 
 PostHog
   module_doc: documented