Skip to content

DevNullLtd/Yuzu / .claude/skills/gateway-dialyzer

gateway-dialyzer

Verified

Run dialyzer over the Yuzu Erlang gateway. Sources the Erlang toolchain and runs rebar3 dialyzer. Use after any .erl change in gateway/ — CLAUDE.md mandates dialyzer be clean before commit because compilation success does not imply type correctness.

FileKindSize
SKILL.mdskill md4.1 KB
---
name: gateway-dialyzer
description: Run dialyzer over the Yuzu Erlang gateway. Sources the Erlang toolchain and runs rebar3 dialyzer. Use after any .erl change in gateway/ — CLAUDE.md mandates dialyzer be clean before commit because compilation success does not imply type correctness.
---

# gateway-dialyzer

Runbook for static type analysis on the Yuzu Erlang gateway. **Mandatory after every `.erl` change** per CLAUDE.md.

## Command

From the repo root:

```bash
source scripts/ensure-erlang.sh >/dev/null && \
  command -v erl >/dev/null || { echo "Erlang missing"; exit 1; }
cd gateway && rebar3 dialyzer
```

First run on a fresh checkout builds the PLT (persistent lookup table) for the full OTP + dependency closure — this takes 2-5 minutes. Subsequent runs are incremental and complete in 10-30 seconds. The PLT lives under `_build/default/rebar3_<otp>_plt`; if it gets corrupted, delete it and rerun.

## Why this is mandatory

`rebar.config` uses `warnings_as_errors` for compile, so compile warnings block the build. But dialyzer warnings are separate — the compiler silently accepts:
- `-spec` contract violations (function called with an arg that the spec rejects)
- Unreachable patterns in case clauses
- Dead code from structurally impossible states
- Missing dependencies (functions called from modules not listed in `applications`)
- Opaque type leaks

Dialyzer catches all of these. Skipping dialyzer is how the gateway acquires silent type bugs that only surface weeks later.

## Interpreting output

- **No output after "Analyzing N files ..."** — clean, no findings. Exit code 0.
- **`Unknown functions:` / `Unknown types:`** — a transitive dep is missing from the `applications` list in `yuzu_gw.app.src`. Rule: **if you call a function from a transitive dependency, add its owning app to `applications`.** `ctx` is the canonical example — the gRPC layer's request-context type, which used to arrive transitively through `grpcbox` (now gone) and which we call directly (`ctx:get/3`, `ctx:t()` in specs), so it must be listed explicitly or dialyzer can't find it in the PLT. Apps that only appear in callback types (`cowlib`, `gun`) go in `rebar.config`'s `dialyzer` `plt_extra_apps` instead.
- **`The call ... will never return since it differs in arguments from the success typing`** — the call arguments contradict the callee's `-spec`. Fix the caller, not the spec (unless the spec is wrong).
- **`The variable _ can never match since previous clauses completely covered the type`** — dead code from a structurally impossible state. Delete the catchall. The circuit breaker's `on_success/on_failure` functions are the canonical example: only `closed` and `half_open` are reachable because `check_circuit/1` rejects `open` before the RPC runs, so a `_ -> ...` catchall is unreachable.
- **`Plugin gpb does not export init/1`** — benign warning from rebar3 itself, not dialyzer. gpb is used via `grpc` config, not as a rebar3 plugin. Ignore.

## Known pitfalls

| Symptom | Root cause | Fix |
|---------|-----------|-----|
| Dialyzer can't find a function you can clearly see in a dep's source | Dep is transitive, not in `applications` | Add the app to `yuzu_gw.app.src` `applications` list |
| Warnings about a fallback clause you added "just in case" | The -spec declares it unreachable | Delete the clause; respect the spec |
| PLT-related errors after an OTP upgrade | Stale PLT from prior OTP version | `rm -rf gateway/_build/default/rebar3_*_plt` and rerun |
| Warnings you don't understand after adding a new dep | New dep's types weren't added to the PLT | `rebar3 dialyzer --update-plt` (automatic on next run anyway) |

## Workflow discipline

Per CLAUDE.md, the required sequence after any gateway `.erl` edit is:
1. `rebar3 compile` — catches syntax + explicit compile warnings
2. `gateway-eunit` skill — catches runtime behavior regressions
3. `gateway-dialyzer` (this skill) — catches type violations and dead code
4. Commit only if all three are clean

If dialyzer reports a warning you believe is wrong, do not suppress it — investigate. Every dialyzer warning that was "known and benign" has, at some point, turned out to be a real bug.
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall