Sync upstream v11.0.0 (merge conflicts)

.agents/skills/elixir-clause-grouping/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: elixir-clause-grouping
+description: Use when refactoring Elixir multi-clause functions, extracting helper functions, or fixing Credo readability warnings caused by placing `defp` helpers between clauses of the same function. Keeps function clauses contiguous and moves helpers below the full clause group.
+---
+
+## Overview
+
+In Elixir modules, all clauses of the same function should stay together. Inserting a `defp` helper between clauses of a `def` or `defp` makes the function harder to read and can trigger Credo readability warnings. When shared logic needs to be extracted, keep the original clause group contiguous and place the helper after the full group.
+
+## When to Use
+
+- When refactoring a multi-clause `def` or `defp`
+- When extracting duplicated logic from multiple function clauses
+- When addressing Credo warnings about clause grouping or readability
+- When editing controller, view, or context modules with several clauses of the same function
+- During review when a helper was added in the middle of another function's clauses
+
+## Core Rule
+
+- Keep all clauses of the same function contiguous
+- Do not place `defp` helpers between clauses of another function
+- Extract shared logic into a helper placed after the full clause group
+
+## Anti-Pattern
+
+```elixir
+def decoded_input_data(%Transaction{to_address: nil}, _, _, _, _), do: {:error, :no_to_address}
+
+defp decode_input_data_with_fallback(data, abi, input, hash, skip_sig_provider?, options, methods_map, abi_map) do
+  ...
+end
+
+def decoded_input_data(%Transaction{to_address: %NotLoaded{}}, _, _, _, _), do: {:error, :contract_not_verified, []}
+```
+
+This splits the `decoded_input_data/5` clause group and makes the function harder to scan.
+
+## Preferred Pattern
+
+```elixir
+def decoded_input_data(%Transaction{to_address: nil}, _, _, _, _), do: {:error, :no_to_address}
+
+def decoded_input_data(%Transaction{to_address: %NotLoaded{}}, _, _, _, _), do: {:error, :contract_not_verified, []}
+
+def decoded_input_data(%Transaction{to_address: %{smart_contract: smart_contract}} = transaction, skip_sig_provider?, options, methods_map, abi_map) do
+  ...
+end
+
+defp decode_input_data_with_fallback(data, abi, input, hash, skip_sig_provider?, options, methods_map, abi_map) do
+  ...
+end
+```
+
+## Refactoring Checklist
+
+1. Identify every clause of the function being edited.
+2. Keep those clauses adjacent to each other.
+3. Extract shared logic only after the full clause group.
+4. Re-check that no unrelated `def` or `defp` appears inside the group.
+5. Run formatting after the refactor.
+
+## Notes
+
+- This applies to both public and private multi-clause functions.
+- If a helper is only used by one clause group, place it immediately after that group.
+- Preserving clause grouping is preferred even when the extracted helper is small.

.agents/skills/update-common-blockscout-env/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: update-common-blockscout-env
+description: Ensure every newly introduced environment variable is also added to docker-compose/envs/common-blockscout.env so local Docker setups stay aligned with runtime configuration.
+---
+
+## Overview
+
+This skill keeps environment-variable documentation and defaults in sync for Docker users.
+
+When adding or changing runtime env vars (for example in config/runtime.exs), also update docker-compose/envs/common-blockscout.env in the same task.
+
+## Mandatory Rule
+
+- Every new env variable introduced in code/config must be added to docker-compose/envs/common-blockscout.env.
+- Do not postpone this to a follow-up task.
+
+## How To Apply
+
+1. Identify newly added env vars in changed files (typically config/runtime.exs, config/*.exs, or modules reading System.get_env/1-2).
+2. Add each variable to docker-compose/envs/common-blockscout.env.
+3. Place it in the most relevant section (for example API flags near other API_* variables).
+4. Prefer non-breaking defaults:
+   - Use a commented example line for optional flags (for example # MY_FLAG=false).
+   - Use an uncommented value only when the project convention requires a default to be active.
+5. Keep naming and formatting consistent with existing entries.
+
+## Checklist
+
+- New env var exists in code.
+- Matching entry exists in docker-compose/envs/common-blockscout.env.
+- Placement is logical and discoverable.
+- Default value does not change behavior unexpectedly.
+
+## Example
+
+If code adds:
+
+- DISABLE_TRANSACTIONS_BENS_PRELOAD
+
+Then docker-compose/envs/common-blockscout.env should include:
+
+- # DISABLE_TRANSACTIONS_BENS_PRELOAD=false

.agents/skills/with-to-case-refactor/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: with-to-case-refactor
+description: Replace `with` expressions that contain only a single `<-` clause and an `else` branch with a `case` expression. This addresses the Credo warning "with contains only one <- clause and an else branch, consider using case instead" and produces cleaner, more idiomatic Elixir code.
+---
+
+## Overview
+
+Elixir's `with` construct is designed for chaining multiple pattern-matching steps. When only one `<-` clause is present alongside an `else` branch, `with` adds no value over a plain `case`. Credo flags this as:
+
+```
+[R] → `with` contains only one <- clause and an `else` branch, consider using `case` instead
+```
+
+Always prefer `case` in this situation.
+
+## When to Use
+
+- When a `with` expression has exactly one `<-` clause and one or more `else` arms.
+- When refactoring code to address the Credo `Credo.Check.Refactor.WithClauses` warning.
+
+## Anti-Pattern (Avoid)
+
+```elixir
+# ❌ BAD: single-clause with/else — should be a case
+with {:ok, response} <- json_rpc(params, opts) do
+  process(response)
+else
+  {:error, reason} ->
+    Logger.error("RPC failed: #{inspect(reason)}")
+    :error
+end
+```
+
+```elixir
+# ❌ BAD: single-clause with/else wrapping a nested case
+with {:ok, response} <- json_rpc(params, opts) do
+  case parse(response) do
+    {:ok, value} -> value
+    _            -> :error
+  end
+else
+  {:error, reason} ->
+    Logger.error("RPC failed: #{inspect(reason)}")
+    :error
+end
+```
+
+## Best Practice (Use Instead)
+
+```elixir
+# ✅ GOOD: flat case replaces with/else
+case json_rpc(params, opts) do
+  {:ok, response} ->
+    process(response)
+
+  {:error, reason} ->
+    Logger.error("RPC failed: #{inspect(reason)}")
+    :error
+end
+```
+
+```elixir
+# ✅ GOOD: nested case is fine when the outer with is replaced
+case json_rpc(params, opts) do
+  {:ok, response} ->
+    case parse(response) do
+      {:ok, value} -> value
+      _            -> :error
+    end
+
+  {:error, reason} ->
+    Logger.error("RPC failed: #{inspect(reason)}")
+    :error
+end
+```
+
+## Transformation Rules
+
+1. Move the expression on the right-hand side of `<-` to become the subject of `case`.
+2. Turn the left-hand side of `<-` into the matching branch of `case`.
+3. Move the body of the `with` block as the body of that `case` branch.
+4. Move each arm of the `else` block as additional `case` branches.
+5. Remove the `with`/`else`/`end` wrapper.
+
+## Real-World Example (from this codebase)
+
+### Before
+
+```elixir
+with {:ok, response} <-
+       params
+       |> Map.merge(%{id: 0})
+       |> Nonce.request()
+       |> json_rpc(json_rpc_named_arguments) do
+  case Nonce.from_response(%{id: 0, result: response}, id_to_params) do
+    {:ok, %{nonce: 0}} -> handle_zero_nonce(...)
+    {:ok, %{nonce: nonce}} when nonce > 0 -> handle_nonzero_nonce(...)
+    _ -> retry(...)
+  end
+else
+  {:error, reason} ->
+    Logger.error("Error: #{inspect(reason)}")
+    retry(...)
+end
+```
+
+### After
+
+```elixir
+case params
+     |> Map.merge(%{id: 0})
+     |> Nonce.request()
+     |> json_rpc(json_rpc_named_arguments) do
+  {:ok, response} ->
+    case Nonce.from_response(%{id: 0, result: response}, id_to_params) do
+      {:ok, %{nonce: 0}} -> handle_zero_nonce(...)
+      {:ok, %{nonce: nonce}} when nonce > 0 -> handle_nonzero_nonce(...)
+      _ -> retry(...)
+    end
+
+  {:error, reason} ->
+    Logger.error("Error: #{inspect(reason)}")
+    retry(...)
+end
+```
+
+## Notes
+
+- If the `with` has **two or more** `<-` clauses, keep it as `with`; this refactor only applies to the single-clause case.
+- If there is no `else` branch at all, `with` is also acceptable for a single clause — but a `case` is still clearer and preferred.
+- After refactoring, run `mix format` to ensure correct indentation.