DevNullLtd/Yuzu / .claude/skills/gateway-dialyzer
gateway-dialyzer
UnverifiedRun 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:
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:
-speccontract 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 theapplicationslist inyuzu_gw.app.src. Rule: if you call a function from a transitive dependency, add its owning app toapplications.ctxis the canonical example — the gRPC layer's request-context type, which used to arrive transitively throughgrpcbox(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 inrebar.config'sdialyzerplt_extra_appsinstead.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'son_success/on_failurefunctions are the canonical example: onlyclosedandhalf_openare reachable becausecheck_circuit/1rejectsopenbefore 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 viagrpcconfig, 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:
rebar3 compile— catches syntax + explicit compile warningsgateway-eunitskill — catches runtime behavior regressionsgateway-dialyzer(this skill) — catches type violations and dead code- 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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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 implementation | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| 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 fallback | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| 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 always | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |