refactor: Expand handle_error opts to explicit positional arguments

Replaces the trailing keyword opts with 5 named positional args with
defaults: stacktrace, user_context, additional_context, fingerprint,
custom_description. Bumps FunctionArity max_arity to 9 in .credo.exs
to accommodate the intentionally explicit public API.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: Jez-A

.credo.exs

@@ -117,7 +117,7 @@
           {Credo.Check.Refactor.Apply, []},
           {Credo.Check.Refactor.CondStatements, []},
           {Credo.Check.Refactor.CyclomaticComplexity, []},
-          {Credo.Check.Refactor.FunctionArity, []},
+          {Credo.Check.Refactor.FunctionArity, [max_arity: 9]},
           {Credo.Check.Refactor.LongQuoteBlocks, []},
           {Credo.Check.Refactor.MatchInCondition, []},
           {Credo.Check.Refactor.MapJoin, []},

lib/zexbox/auto_escalation.ex

@@ -22,9 +22,9 @@ defmodule Zexbox.AutoEscalation do
         "checkout",
         "High",
         "Purchase Ops",
-        stacktrace: __STACKTRACE__,
-        user_context: %{email: user.email},
-        additional_context: %{basket_id: basket.id}
+        __STACKTRACE__,
+        %{email: user.email},
+        %{basket_id: basket.id}
       )
   end
   ```
@@ -54,9 +54,9 @@ defmodule Zexbox.AutoEscalation do
   ```
   """
 
-  require Logger
+  alias Zexbox.{AutoEscalation.AdfBuilder, JiraClient}
 
-  alias Zexbox.{JiraClient, AutoEscalation.AdfBuilder}
+  require Logger
 
   defmodule Error do
     @moduledoc "Raised when Jira ticket creation or transition fails."
@@ -80,18 +80,47 @@ defmodule Zexbox.AutoEscalation do
   - `priority` – Jira priority name (e.g. `"High"`).
   - `zigl_team` – value for the ZIGL Team custom field.
 
-  Optional options:
-  - `:stacktrace` – pass `__STACKTRACE__` from the rescue block for a full trace.
-  - `:user_context` – map rendered as a bullet list in the ticket body.
-  - `:additional_context` – map of extra key/value pairs in the ticket body.
-  - `:fingerprint` – override deduplication key; defaults to `"action::ErrorClass"`.
-  - `:custom_description` – string rendered above Error Details (split on `\\n\\n`).
+  Optional arguments (all default to `nil` or empty):
+  - `stacktrace` – pass `__STACKTRACE__` from the rescue block for a full trace.
+  - `user_context` – map rendered as a bullet list in the ticket body.
+  - `additional_context` – map of extra key/value pairs in the ticket body.
+  - `fingerprint` – override deduplication key; auto-generated as `"action::ErrorClass"` when `nil`.
+  - `custom_description` – string rendered above Error Details (split on `\\n\\n`).
   """
-  @spec handle_error(Exception.t(), String.t(), String.t(), String.t(), keyword()) ::
-          {:ok, map()} | {:error, term()} | {:disabled, nil}
-  def handle_error(error, action, priority, zigl_team, opts \\ []) do
+  @spec handle_error(
+          Exception.t(),
+          String.t(),
+          String.t(),
+          String.t(),
+          Exception.stacktrace() | nil,
+          map(),
+          map(),
+          String.t() | nil,
+          String.t() | nil
+        ) :: {:ok, map()} | {:error, term()} | {:disabled, nil}
+  def handle_error(
+        error,
+        action,
+        priority,
+        zigl_team,
+        stacktrace \\ nil,
+        user_context \\ %{},
+        additional_context \\ %{},
+        fingerprint \\ nil,
+        custom_description \\ nil
+      ) do
     if auto_escalation_enabled?() do
-      do_handle_error(error, action, priority, zigl_team, opts)
+      do_handle_error(
+        error,
+        action,
+        priority,
+        zigl_team,
+        stacktrace,
+        user_context,
+        additional_context,
+        fingerprint,
+        custom_description
+      )
     else
       {:disabled, nil}
     end
@@ -110,21 +139,23 @@ defmodule Zexbox.AutoEscalation do
 
   # --- Private ---
 
-  defp do_handle_error(error, action, priority, zigl_team, opts) do
+  defp do_handle_error(
+         error,
+         action,
+         priority,
+         zigl_team,
+         stacktrace,
+         user_context,
+         additional_context,
+         fingerprint_override,
+         custom_description
+       ) do
     unless is_exception(error) do
       raise ArgumentError, "Expected an Exception.t() for :error, got: #{inspect(error)}"
     end
 
-    user_context = Keyword.get(opts, :user_context, %{})
-    additional_context = Keyword.get(opts, :additional_context, %{})
-    stacktrace = Keyword.get(opts, :stacktrace)
-    custom_description = Keyword.get(opts, :custom_description)
-
     error_class = inspect(error.__struct__)
-
-    fingerprint =
-      Keyword.get(opts, :fingerprint) ||
-        generate_fingerprint(error_class, action)
+    fingerprint = fingerprint_override || generate_fingerprint(error_class, action)
 
     case find_existing_ticket(fingerprint) do
       nil ->
@@ -166,7 +197,7 @@ defmodule Zexbox.AutoEscalation do
       {:ok, []} ->
         nil
 
-      {:ok, [first | _]} ->
+      {:ok, [first | _rest]} ->
         first
 
       {:error, e} ->
@@ -215,7 +246,7 @@ defmodule Zexbox.AutoEscalation do
              priority,
              custom_fields
            ),
-         {:ok, _} <- JiraClient.transition_issue(result["key"], @transition_to) do
+         {:ok, _resp} <- JiraClient.transition_issue(result["key"], @transition_to) do
       {:ok, result}
     else
       {:error, e} ->
@@ -249,7 +280,7 @@ defmodule Zexbox.AutoEscalation do
       )
 
     case JiraClient.add_comment(issue_key, comment) do
-      {:ok, _} ->
+      {:ok, _resp} ->
         :ok
 
       {:error, e} ->

test/zexbox/auto_escalation_test.exs

@@ -122,7 +122,7 @@ defmodule Zexbox.AutoEscalationTest do
     end
   end
 
-  describe "handle_error/5 — when disabled" do
+  describe "handle_error/9 — when disabled" do
     test "returns {:disabled, nil} without calling Jira" do
       Application.put_env(:zexbox, :auto_escalation_enabled, false)
 
@@ -136,7 +136,7 @@ defmodule Zexbox.AutoEscalationTest do
     end
   end
 
-  describe "handle_error/5 — new ticket path" do
+  describe "handle_error/9 — new ticket path" do
     test "returns {:ok, ticket} and calls create_issue" do
       with_mocks(all_mocks()) do
         assert {:ok, ticket} =
@@ -217,8 +217,15 @@ defmodule Zexbox.AutoEscalationTest do
 
     test "uses custom fingerprint override when provided" do
       with_mocks(all_mocks(capture_create_issue())) do
-        AutoEscalation.handle_error(error(), "checkout", "High", "Ops",
-          fingerprint: "custom::fingerprint"
+        AutoEscalation.handle_error(
+          error(),
+          "checkout",
+          "High",
+          "Ops",
+          nil,
+          %{},
+          %{},
+          "custom::fingerprint"
         )
 
         assert_received {:create_opts, opts}
@@ -228,9 +235,14 @@ defmodule Zexbox.AutoEscalationTest do
 
     test "description is a valid ADF doc map" do
       with_mocks(all_mocks(capture_create_issue())) do
-        AutoEscalation.handle_error(error(), "pay", "Medium", "Payments",
-          user_context: %{email: "u@example.com"},
-          additional_context: %{basket_id: 123}
+        AutoEscalation.handle_error(
+          error(),
+          "pay",
+          "Medium",
+          "Payments",
+          nil,
+          %{email: "u@example.com"},
+          %{basket_id: 123}
         )
 
         assert_received {:create_opts, opts}
@@ -272,7 +284,7 @@ defmodule Zexbox.AutoEscalationTest do
     end
   end
 
-  describe "handle_error/5 — existing ticket path" do
+  describe "handle_error/9 — existing ticket path" do
     test "returns the existing ticket and adds a comment" do
       jira_overrides = [
         search_latest_issues: fn _jql, _project_key -> {:ok, [@existing_ticket]} end
@@ -322,7 +334,7 @@ defmodule Zexbox.AutoEscalationTest do
     end
   end
 
-  describe "handle_error/5 — search failure" do
+  describe "handle_error/9 — search failure" do
     test "logs and falls through to create a new ticket when search fails" do
       jira_overrides = [
         search_latest_issues: fn _jql, _project_key -> {:error, "Search failed"} end