Skip to content

DevNullLtd/Yuzu / .codex/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/ — 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:

  • -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.
  • 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

SymptomRoot causeFix
Dialyzer can't find a function you can clearly see in a dep's sourceDep is transitive, not in applicationsAdd the app to yuzu_gw.app.src applications list
Warnings about a fallback clause you added "just in case"The -spec declares it unreachableDelete the clause; respect the spec
PLT-related errors after an OTP upgradeStale PLT from prior OTP versionrm -rf gateway/_build/default/rebar3_*_plt and rerun
Warnings you don't understand after adding a new depNew dep's types weren't added to the PLTrebar3 dialyzer --update-plt (automatic on next run anyway)

Workflow discipline

Per AGENTS.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.

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: 467kUpdated Claude CodeCodexVerifiedInstall
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: 319kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 319kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 319kUpdated Claude CodeCodexVerifiedInstall