diff --git a/lib/mix/tasks/posthog.public_api.ex b/lib/mix/tasks/posthog.public_api.ex index b12d2ed..4dd4eed 100644 --- a/lib/mix/tasks/posthog.public_api.ex +++ b/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() diff --git a/public_api.snapshot b/public_api.snapshot index 9a7067f..5f0b79f 100644 --- a/public_api.snapshot +++ b/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