DevNullLtd/Yuzu / .codex/skills/gateway-dialyzer
gateway-dialyzer
VerifiedRun dialyzer over the Yuzu Erlang gateway. Sources the Erlang toolchain and runs rebar3 dialyzer. Use after any .erl change in gateway/ — AGENTS.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 AGENTS.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.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 AGENTS.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 |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |