refactor(types): reconcile @specs with their success typings

lib/mv/membership/import/csv_parser.ex

@@ -100,7 +100,8 @@ defmodule Mv.Membership.Import.CsvParser do
     |> String.replace("\r", "\n")
   end
 
-  @spec get_parser(String.t()) :: module()
+  @spec get_parser(String.t()) ::
+          Mv.Membership.Import.CsvParserSemicolon | Mv.Membership.Import.CsvParserComma
   defp get_parser(";"), do: Mv.Membership.Import.CsvParserSemicolon
   defp get_parser(","), do: Mv.Membership.Import.CsvParserComma
   defp get_parser(_), do: Mv.Membership.Import.CsvParserSemicolon
@@ -116,7 +117,10 @@ defmodule Mv.Membership.Import.CsvParser do
     if semicolon_score >= comma_score, do: ";", else: ","
   end
 
-  @spec header_field_count(module(), binary()) :: non_neg_integer()
+  @spec header_field_count(
+          Mv.Membership.Import.CsvParserSemicolon | Mv.Membership.Import.CsvParserComma,
+          binary()
+        ) :: non_neg_integer()
   defp header_field_count(parser, header_record) do
     case parse_single_record(parser, header_record, nil) do
       {:ok, fields} -> Enum.count(fields, &(String.trim(&1) != ""))

lib/mv/membership/member_export.ex

@@ -16,6 +16,21 @@ defmodule Mv.Membership.MemberExport do
   alias MvWeb.MemberLive.Index
   alias MvWeb.MemberLive.Index.MembershipFeeStatus
 
+  @typedoc "Validated export parameters produced by `parse_params/1`."
+  @type parsed_params :: %{
+          selected_ids: [String.t()],
+          member_fields: [String.t()],
+          selectable_member_fields: [String.t()],
+          computed_fields: [String.t()],
+          custom_field_ids: [String.t()],
+          query: String.t() | nil,
+          sort_field: String.t() | nil,
+          sort_order: String.t() | nil,
+          show_current_cycle: boolean(),
+          cycle_status_filter: :paid | :unpaid | nil,
+          boolean_filters: %{optional(String.t()) => boolean()}
+        }
+
   @member_fields_allowlist (Mv.Constants.member_fields() |> Enum.map(&Atom.to_string/1)) ++
                              ["membership_fee_type", "membership_fee_status", "groups"]
   @computed_export_fields ["membership_fee_status"]
@@ -305,7 +320,7 @@ defmodule Mv.Membership.MemberExport do
   :computed_fields, :custom_field_ids, :query, :sort_field, :sort_order,
   :show_current_cycle, :cycle_status_filter, :boolean_filters.
   """
-  @spec parse_params(map()) :: map()
+  @spec parse_params(map()) :: parsed_params()
   def parse_params(params) do
     # DB fields come from "member_fields"
     raw_member_fields = extract_list(params, "member_fields")

lib/mv/membership/members_csv.ex

@@ -21,7 +21,7 @@ defmodule Mv.Membership.MembersCSV do
   Returns iodata suitable for `IO.iodata_to_binary/1` or sending as response body.
   RFC 4180 escaping and formula-injection safe_cell are applied.
   """
-  @spec export([struct() | map()], [map()]) :: iodata()
+  @spec export([struct() | map()], [map()]) :: [iodata()] | Enumerable.t()
   def export(members, columns) when is_list(members) do
     header = build_header(columns)
     rows = Enum.map(members, fn member -> build_row(member, columns) end)