Typespecs and Dialyzer

defmodule Math do
  @spec add(number(), number()) :: number()
  def add(a, b), do: a + b

  @spec divide(number(), number()) :: {:ok, float()} | {:error, String.t()}
  def divide(_a, 0), do: {:error, "division by zero"}
  def divide(a, b), do: {:ok, a / b}

  @spec factorial(non_neg_integer()) :: pos_integer()
  def factorial(0), do: 1
  def factorial(n) when n > 0, do: n * factorial(n - 1)
end

defmodule User do
  @type t :: %__MODULE__{
    name: String.t(),
    email: String.t(),
    age: non_neg_integer(),
    role: role()
  }

  @type role :: :admin | :editor | :viewer

  # Private type -- only visible within this module
  @typep internal_id :: pos_integer()

  # Opaque type -- visible to other modules by name,
  # but they should not inspect its internal structure
  @opaque token :: {internal_id(), String.t()}

  defstruct [:name, :email, :age, :role]

  @spec new(String.t(), String.t(), non_neg_integer(), role()) :: t()
  def new(name, email, age, role \\ :viewer) do
    %__MODULE__{name: name, email: email, age: age, role: role}
  end

  @spec admin?(t()) :: boolean()
  def admin?(%__MODULE__{role: :admin}), do: true
  def admin?(_user), do: false
end

defmodule Config do
  @type value :: String.t() | integer() | boolean() | nil
  @type config :: %{optional(atom()) => value()}

  @spec get(config(), atom()) :: value()
  def get(config, key), do: Map.get(config, key)

  @spec get(config(), atom(), value()) :: value()
  def get(config, key, default), do: Map.get(config, key, default)

  @spec fetch!(config(), atom()) :: value()
  def fetch!(config, key) do
    case Map.fetch(config, key) do
      {:ok, val} -> val
      :error     -> raise KeyError, key: key, term: config
    end
  end
end

# In mix.exs, add to deps:
defp deps do
  [
    {:dialyxir, "~> 1.4", only: [:dev, :test], runtime: false}
  ]
end

# First run builds the PLT (Persistent Lookup Table)
# This takes several minutes but only happens once
mix dialyzer

# Subsequent runs are much faster
mix dialyzer

defmodule Problematic do
  # Warning: function has no local return
  # (the function can never successfully return)
  @spec always_fails() :: :ok
  def always_fails do
    raise "boom"
    :ok  # unreachable code
  end

  # Warning: the pattern can never match
  @spec check(integer()) :: String.t()
  def check(x) when is_integer(x) do
    case x do
      _ when is_binary(x) -> x  # impossible -- x is an integer
      _ -> "number"
    end
  end

  # Warning: contract violation
  # The spec says String.t() but function returns an atom
  @spec name() :: String.t()
  def name, do: :alice
end

def project do
  [
    app: :my_app,
    # ... other config
    dialyzer: [
      plt_add_apps: [:mnesia],           # include extra apps in PLT
      flags: [
        :unmatched_returns,               # warn on ignored return values
        :error_handling,                   # warn on error handling issues
        :underspecs,                       # warn when spec is too broad
        :no_opaque                         # warn on opaque type violations
      ],
      ignore_warnings: ".dialyzer_ignore.exs"
    ]
  ]
end

defmodule Cache do
  @type key :: String.t()
  @type value :: term()
  @type ttl :: pos_integer() | :infinity

  @callback get(key()) :: {:ok, value()} | :miss
  @callback put(key(), value(), ttl()) :: :ok
  @callback delete(key()) :: :ok

  @optional_callbacks [delete: 1]
end

defmodule ETSCache do
  @behaviour Cache

  @impl Cache
  @spec get(Cache.key()) :: {:ok, Cache.value()} | :miss
  def get(key) do
    case :ets.lookup(:cache, key) do
      [{^key, val}] -> {:ok, val}
      []            -> :miss
    end
  end

  @impl Cache
  @spec put(Cache.key(), Cache.value(), Cache.ttl()) :: :ok
  def put(key, value, _ttl) do
    :ets.insert(:cache, {key, value})
    :ok
  end
end

defmodule Payments do
  @type currency :: :usd | :eur | :gbp
  @type amount :: pos_integer()
  @type transfer_error :: :insufficient_funds | :account_locked | :invalid_currency

  @spec transfer(String.t(), String.t(), amount(), currency()) ::
          :ok | {:error, transfer_error()}
  def transfer(from_id, to_id, amount, currency) do
    # implementation omitted
  end
end