fix: resolve credo and dialyzer warnings

Extract helper functions to reduce nesting depth in calibrate, setup_servos,
and controller modules. Use catch-all error patterns in command handlers to
satisfy dialyzer (can't trace through `:telemetry.span/3`). Fix nested module
aliases in Phoenix boilerplate.

Author: jimsynz

lib/bb/example/so101/command/demo_circle.ex

@@ -37,6 +37,10 @@ defmodule BB.Example.SO101.Command.DemoCircle do
   @default_points 16
   @default_delay 150
 
+  # Motion.move_to/4 can return errors at runtime but dialyzer can't see
+  # through :telemetry.span/3 and thinks it always returns {:ok, meta}
+  @dialyzer {:no_match, [handle_command: 3, execute_path: 4]}
+
   @impl BB.Command
   def handle_command(goal, context, state) do
     radius = Map.get(goal, :radius, @default_radius)
@@ -66,8 +70,8 @@ defmodule BB.Example.SO101.Command.DemoCircle do
             {:stop, :normal, %{state | result: {:error, reason}}}
         end
 
-      {:error, reason, _meta} ->
-        {:stop, :normal, %{state | result: {:error, {:failed_to_reach_start, reason}}}}
+      error ->
+        {:stop, :normal, %{state | result: {:error, {:failed_to_reach_start, error}}}}
     end
   end
 
@@ -92,8 +96,8 @@ defmodule BB.Example.SO101.Command.DemoCircle do
           Process.sleep(delay)
           {:cont, :ok}
 
-        {:error, reason, _meta} ->
-          {:halt, {:error, {:ik_failed, target, reason}}}
+        error ->
+          {:halt, {:error, {:ik_failed, target, error}}}
       end
     end)
   end

lib/bb/example/so101/command/move_to_pose.ex

@@ -22,6 +22,10 @@ defmodule BB.Example.SO101.Command.MoveToPose do
   alias BB.IK.DLS.Motion
   alias BB.Math.Vec3
 
+  # Motion.move_to/4 can return errors at runtime but dialyzer can't see
+  # through :telemetry.span/3 and thinks it always returns {:ok, meta}
+  @dialyzer {:no_match, handle_command: 3}
+
   @impl BB.Command
   def handle_command(%{target: %Vec3{} = target}, context, state) do
     ik_opts = [delivery: :direct, exclude_joints: [:gripper]]
@@ -30,8 +34,8 @@ defmodule BB.Example.SO101.Command.MoveToPose do
       {:ok, _meta} ->
         {:stop, :normal, %{state | result: :reached}}
 
-      {:error, reason, _meta} ->
-        {:stop, :normal, %{state | result: {:error, {:ik_failed, reason}}}}
+      error ->
+        {:stop, :normal, %{state | result: {:error, {:ik_failed, error}}}}
     end
   end
 

lib/bb_example_so101/application.ex

@@ -9,6 +9,8 @@ defmodule BB.Example.SO101.Application do
 
   use Application
 
+  alias BB.Example.SO101Web
+
   @impl true
   def start(_type, _args) do
     children =
@@ -30,7 +32,7 @@ defmodule BB.Example.SO101.Application do
   # whenever the application is updated.
   @impl true
   def config_change(changed, _new, removed) do
-    BB.Example.SO101Web.Endpoint.config_change(changed, removed)
+    SO101Web.Endpoint.config_change(changed, removed)
     :ok
   end
 

lib/bb_example_so101_web.ex

@@ -92,8 +92,8 @@ defmodule BB.Example.SO101Web do
       import BB.Example.SO101Web.CoreComponents
 
       # Common modules used in templates
-      alias Phoenix.LiveView.JS
       alias BB.Example.SO101Web.Layouts
+      alias Phoenix.LiveView.JS
 
       # Routes generation with the ~p sigil
       unquote(verified_routes())
@@ -103,9 +103,9 @@ defmodule BB.Example.SO101Web do
   def verified_routes do
     quote do
       use Phoenix.VerifiedRoutes,
-        endpoint: BB.Example.SO101Web.Endpoint,
-        router: BB.Example.SO101Web.Router,
-        statics: BB.Example.SO101Web.static_paths()
+        endpoint: unquote(Module.concat(__MODULE__, Endpoint)),
+        router: unquote(Module.concat(__MODULE__, Router)),
+        statics: unquote(__MODULE__).static_paths()
     end
   end
 

lib/bb_example_so101_web/components/core_components.ex

@@ -33,6 +33,7 @@ defmodule BB.Example.SO101Web.CoreComponents do
   use Phoenix.Component
   use Gettext, backend: BB.Example.SO101Web.Gettext
 
+  alias Phoenix.HTML.Form
   alias Phoenix.LiveView.JS
 
   @doc """
@@ -205,7 +206,7 @@ defmodule BB.Example.SO101Web.CoreComponents do
   def input(%{type: "checkbox"} = assigns) do
     assigns =
       assign_new(assigns, :checked, fn ->
-        Phoenix.HTML.Form.normalize_value("checkbox", assigns[:value])
+        Form.normalize_value("checkbox", assigns[:value])
       end)
 
     ~H"""

lib/bb_example_so101_web/endpoint.ex

@@ -5,6 +5,8 @@
 defmodule BB.Example.SO101Web.Endpoint do
   use Phoenix.Endpoint, otp_app: :bb_example_so101
 
+  alias BB.Example.SO101Web
+
   # The session will be stored in the cookie and signed,
   # this means its contents can be read but not tampered with.
   # Set :encryption_salt if you would also like to encrypt it.
@@ -28,7 +30,7 @@ defmodule BB.Example.SO101Web.Endpoint do
     at: "/",
     from: :bb_example_so101,
     gzip: not code_reloading?,
-    only: BB.Example.SO101Web.static_paths(),
+    only: SO101Web.static_paths(),
     raise_on_missing_only: code_reloading?
 
   plug Plug.Static,
@@ -63,5 +65,5 @@ defmodule BB.Example.SO101Web.Endpoint do
   plug Plug.MethodOverride
   plug Plug.Head
   plug Plug.Session, @session_options
-  plug BB.Example.SO101Web.Router
+  plug SO101Web.Router
 end

lib/mix/tasks/so101.calibrate.ex

@@ -123,22 +123,14 @@ defmodule Mix.Tasks.So101.Calibrate do
   end
 
   defp run_calibration(pid, dry_run) do
-    # Verify all servos are present
     {found, missing} = check_servos(pid)
 
     if missing != [] do
       Mix.shell().error("Missing servos: #{inspect(Enum.map(missing, fn {_, id, _} -> id end))}")
-      Mix.shell().info("Continue anyway? (y/n)")
 
-      case IO.gets("") do
-        data when is_binary(data) ->
-          if String.trim(data) |> String.downcase() != "y" do
-            Mix.shell().info("Calibration cancelled.")
-            return_early()
-          end
-
-        _ ->
-          return_early()
+      unless confirm?("Continue anyway?") do
+        Mix.shell().info("Calibration cancelled.")
+        return_early()
       end
     end
 
@@ -151,21 +143,31 @@ defmodule Mix.Tasks.So101.Calibrate do
       "Found #{length(found)} servo(s). Press Enter to disable torque and begin..."
     )
 
-    case IO.gets("") do
-      data when is_binary(data) ->
-        if String.trim(data) |> String.downcase() == "q" do
-          Mix.shell().info("Calibration cancelled.")
-        else
-          do_calibration(pid, found, dry_run)
-        end
-
-      _ ->
-        Mix.shell().info("Calibration cancelled.")
+    if prompt_quit?() do
+      Mix.shell().info("Calibration cancelled.")
+    else
+      do_calibration(pid, found, dry_run)
     end
   end
 
   defp return_early, do: :ok
 
+  defp confirm?(prompt) do
+    Mix.shell().info(prompt <> " (y/n)")
+
+    case IO.gets("") do
+      data when is_binary(data) -> String.trim(data) |> String.downcase() == "y"
+      _ -> false
+    end
+  end
+
+  defp prompt_quit? do
+    case IO.gets("") do
+      data when is_binary(data) -> String.trim(data) |> String.downcase() == "q"
+      _ -> true
+    end
+  end
+
   defp check_servos(pid) do
     Enum.split_with(@joints, fn {_name, servo_id, _desc} ->
       case Feetech.ping(pid, servo_id) do
@@ -258,24 +260,7 @@ defmodule Mix.Tasks.So101.Calibrate do
         # Read all positions
         new_state =
           Enum.reduce(joints, state, fn {_name, servo_id, _desc}, acc ->
-            case Feetech.read_raw(pid, servo_id, :present_position) do
-              {:ok, raw_pos} ->
-                update_in(acc, [servo_id], fn data ->
-                  # Unwrap position to handle 0/4095 boundary crossing
-                  unwrapped = unwrap_position(raw_pos, data.raw, data.unwrapped)
-
-                  %{
-                    data
-                    | raw: raw_pos,
-                      unwrapped: unwrapped,
-                      min_unwrapped: min(data.min_unwrapped, unwrapped),
-                      max_unwrapped: max(data.max_unwrapped, unwrapped)
-                  }
-                end)
-
-              _ ->
-                acc
-            end
+            update_servo_tracking(pid, servo_id, acc)
           end)
 
         # Display current state
@@ -285,6 +270,26 @@ defmodule Mix.Tasks.So101.Calibrate do
     end
   end
 
+  defp update_servo_tracking(pid, servo_id, state) do
+    case Feetech.read_raw(pid, servo_id, :present_position) do
+      {:ok, raw_pos} ->
+        update_in(state, [servo_id], fn data ->
+          unwrapped = unwrap_position(raw_pos, data.raw, data.unwrapped)
+
+          %{
+            data
+            | raw: raw_pos,
+              unwrapped: unwrapped,
+              min_unwrapped: min(data.min_unwrapped, unwrapped),
+              max_unwrapped: max(data.max_unwrapped, unwrapped)
+          }
+        end)
+
+      _ ->
+        state
+    end
+  end
+
   # Handle position wraparound at 0/4095 boundary
   defp unwrap_position(current_raw, last_raw, last_unwrapped) do
     delta = current_raw - last_raw
@@ -350,42 +355,47 @@ defmodule Mix.Tasks.So101.Calibrate do
     results =
       for {name, servo_id, _desc} <- joints do
         data = state[servo_id]
-        range = data.max_unwrapped - data.min_unwrapped
-
-        if range > 10 do
-          # Calculate center in unwrapped space, then convert to raw (0-4095)
-          center_unwrapped = div(data.min_unwrapped + data.max_unwrapped, 2)
-          center_raw = Integer.mod(center_unwrapped, @steps_per_revolution)
-
-          # Firmware applies: Present_Position = Actual_Position - Offset
-          # So: 2048 = center_raw - offset, therefore offset = center_raw - 2048
-          # Clamp to ±2047 (sign_magnitude bit 11 limit).
-          offset = center_raw - @center_position
-          offset = max(-@max_offset_magnitude, min(@max_offset_magnitude, offset))
-
-          Mix.shell().info("""
-            #{format_joint(name)} (ID #{servo_id}):
-              Range: #{range} steps (#{format_degrees(steps_to_degrees(range))})
-              Center: #{center_raw} -> Offset: #{offset}
-          """)
-
-          if dry_run do
-            {name, servo_id, {:ok, %{range: range, center: center_raw, offset: offset}}}
-          else
-            case apply_calibration(pid, servo_id, offset) do
-              :ok -> {name, servo_id, {:ok, %{offset: offset}}}
-              {:error, reason} -> {name, servo_id, {:error, reason}}
-            end
-          end
-        else
-          Mix.shell().info("  #{format_joint(name)} (ID #{servo_id}): Skipped (not moved enough)")
-          {name, servo_id, {:error, :not_moved}}
-        end
+        process_joint_result(pid, name, servo_id, data, dry_run)
       end
 
     print_summary(results, dry_run)
   end
 
+  defp process_joint_result(_pid, name, servo_id, data, _dry_run)
+       when data.max_unwrapped - data.min_unwrapped <= 10 do
+    Mix.shell().info("  #{format_joint(name)} (ID #{servo_id}): Skipped (not moved enough)")
+    {name, servo_id, {:error, :not_moved}}
+  end
+
+  defp process_joint_result(pid, name, servo_id, data, dry_run) do
+    range = data.max_unwrapped - data.min_unwrapped
+
+    # Calculate center in unwrapped space, then convert to raw (0-4095)
+    center_unwrapped = div(data.min_unwrapped + data.max_unwrapped, 2)
+    center_raw = Integer.mod(center_unwrapped, @steps_per_revolution)
+
+    # Firmware applies: Present_Position = Actual_Position - Offset
+    # So: 2048 = center_raw - offset, therefore offset = center_raw - 2048
+    # Clamp to ±2047 (sign_magnitude bit 11 limit).
+    offset = center_raw - @center_position
+    offset = max(-@max_offset_magnitude, min(@max_offset_magnitude, offset))
+
+    Mix.shell().info("""
+      #{format_joint(name)} (ID #{servo_id}):
+        Range: #{range} steps (#{format_degrees(steps_to_degrees(range))})
+        Center: #{center_raw} -> Offset: #{offset}
+    """)
+
+    if dry_run do
+      {name, servo_id, {:ok, %{range: range, center: center_raw, offset: offset}}}
+    else
+      case apply_calibration(pid, servo_id, offset) do
+        :ok -> {name, servo_id, {:ok, %{offset: offset}}}
+        {:error, reason} -> {name, servo_id, {:error, reason}}
+      end
+    end
+  end
+
   defp reset_position_offset(pid, servo_id) do
     unlock_eeprom(pid, servo_id)
 

lib/mix/tasks/so101.setup_servos.ex

@@ -354,33 +354,35 @@ defmodule Mix.Tasks.So101.SetupServos do
     ════════════════════════════════════════════════════════════════
     """)
 
-    configured = Enum.count(results, fn {_, _, r} -> r in [:configured, :already_configured] end)
-    skipped = Enum.count(results, fn {_, _, r} -> r == :skipped end)
-    failed = Enum.count(results, fn {_, _, r} -> r == :failed end)
-    cancelled = Enum.count(results, fn {_, _, r} -> r == :cancelled end)
-
     for {joint, id, result} <- results do
-      status =
-        case result do
-          :configured -> "✓ Configured"
-          :already_configured -> "✓ Already correct"
-          :skipped -> "○ Skipped"
-          :failed -> "✗ Failed"
-          :cancelled -> "○ Cancelled"
-        end
-
-      Mix.shell().info("  #{format_joint(joint)} (ID #{id}): #{status}")
+      Mix.shell().info("  #{format_joint(joint)} (ID #{id}): #{format_result(result)}")
     end
 
     Mix.shell().info("")
 
-    cond do
-      cancelled > 0 ->
-        Mix.shell().info("Setup was cancelled.")
+    counts = Enum.frequencies_by(results, fn {_, _, r} -> r end)
+    print_summary_message(counts)
+  end
 
-      failed > 0 ->
-        Mix.shell().error("#{failed} servo(s) failed to configure. Please retry those joints.")
+  defp format_result(:configured), do: "✓ Configured"
+  defp format_result(:already_configured), do: "✓ Already correct"
+  defp format_result(:skipped), do: "○ Skipped"
+  defp format_result(:failed), do: "✗ Failed"
+  defp format_result(:cancelled), do: "○ Cancelled"
 
+  defp print_summary_message(%{cancelled: n}) when n > 0 do
+    Mix.shell().info("Setup was cancelled.")
+  end
+
+  defp print_summary_message(%{failed: n}) when n > 0 do
+    Mix.shell().error("#{n} servo(s) failed to configure. Please retry those joints.")
+  end
+
+  defp print_summary_message(counts) do
+    configured = Map.get(counts, :configured, 0) + Map.get(counts, :already_configured, 0)
+    skipped = Map.get(counts, :skipped, 0)
+
+    cond do
       skipped > 0 and configured > 0 ->
         Mix.shell().info("#{configured} servo(s) configured successfully, #{skipped} skipped.")