defmodule Credo.Check.Readability.Specs do
use Credo.Check,
id: "EX3025",
tags: [:controversial],
param_defaults: [
include_defp: false
],
explanations: [
check: """
Functions, callbacks and macros need typespecs.
Adding typespecs gives tools like Dialyzer more information when performing
checks for type errors in function calls and definitions.
@spec add(integer, integer) :: integer
def add(a, b), do: a + b
Functions with multiple arities need to have a spec defined for each arity:
@spec foo(integer) :: boolean
@spec foo(integer, integer) :: boolean
def foo(a), do: a > 0
def foo(a, b), do: a > b
The check only considers whether the specification is present, it doesn't
perform any actual type checking.
Like all `Readability` issues, this one is not a technical concern.
But you can improve the odds of others reading and liking your code by making
it easier to follow.
""",
params: [
include_defp: "Include private functions."
]
]
@doc false
@impl true
def run(%SourceFile{} = source_file, params) do
issue_meta = IssueMeta.for(source_file, params)
specs = Credo.Code.prewalk(source_file, &find_specs(&1, &2))
Credo.Code.prewalk(source_file, &traverse(&1, &2, specs, issue_meta))
end
defp find_specs(
{:spec, _, [{:when, _, [{:"::", _, [{name, _, args}, _]}, _]} | _]} = ast,
specs
) do
{ast, [{name, length(args)} | specs]}
end
defp find_specs({:spec, _, [{_, _, [{name, _, args} | _]}]} = ast, specs)
when is_list(args) or is_nil(args) do
args = with nil <- args, do: []
{ast, [{name, length(args)} | specs]}
end
defp find_specs({:impl, _, [impl]} = ast, specs) when impl != false do
{ast, [:impl | specs]}
end
defp find_specs({keyword, meta, [{:when, _, def_ast} | _]}, [:impl | specs])
when keyword in [:def, :defp] do
find_specs({keyword, meta, def_ast}, [:impl | specs])
end
defp find_specs({keyword, _, [{name, _, nil}, _]} = ast, [:impl | specs])
when keyword in [:def, :defp] do
{ast, [{name, 0} | specs]}
end
defp find_specs({keyword, _, [{name, _, args}, _]} = ast, [:impl | specs])
when keyword in [:def, :defp] do
{ast, [{name, length(args)} | specs]}
end
defp find_specs(ast, issues) do
{ast, issues}
end
defp traverse(
{keyword, meta, [{:when, _, def_ast} | _]},
issues,
specs,
issue_meta
)
when keyword in [:def, :defp] do
traverse({keyword, meta, def_ast}, issues, specs, issue_meta)
end
defp traverse(
{keyword, meta, [{name, _, args} | _]} = ast,
issues,
specs,
issue_meta
)
when is_list(args) or is_nil(args) do
args = with nil <- args, do: []
if keyword not in enabled_keywords(issue_meta) or {name, length(args)} in specs do
{ast, issues}
else
{ast, [issue_for(issue_meta, meta[:line], name) | issues]}
end
end
defp traverse(ast, issues, _specs, _issue_meta) do
{ast, issues}
end
defp issue_for(issue_meta, line_no, trigger) do
trigger =
if is_tuple(trigger) do
Macro.to_string(trigger)
else
trigger
end
format_issue(
issue_meta,
message: "Functions should have a @spec type specification.",
trigger: trigger,
line_no: line_no
)
end
defp enabled_keywords(issue_meta) do
issue_meta
|> IssueMeta.params()
|> Params.get(:include_defp, __MODULE__)
|> case do
true -> [:def, :defp]
_ -> [:def]
end
end
end