%% @doc A rule to detect unnecessary function arguments.
%%      <p>The rule emits a warning for each function argument that is consistently
%%      ignored in all function clauses.</p>
%%      <p>To avoid this warning, remove the unused argument(s).</p>
%%      <h3>Note</h3>
%%      <blockquote>
%%      This rule will not emit a warning if the function
%%      implements a NIF call (assuming that the stub function calls
%%      <code>erlang:nif_error/1,2</code>) or if it's a behaviour callback.
%%      In particular, the rule will not emit a warning for any exported
%%      function in modules that implement non-OTP behaviors or OTP behaviors
%%      that have dynamic callbacks, like <code>gen_statem</code> or <code>ct_suite</code>.
%%      It will also not emit a warning if the function is "known"
%%      even if not in a behaviour, like parse_transform/2.
%%      </blockquote>
-module(unnecessary_function_arguments).

%% Throw is used correctly in this module as a nonlocal return within a fold function
-elvis([{elvis_style, no_throw, disable}]).

-behaviour(hank_rule).

-export([analyze/2, ignored/2]).

%% Known OTP behaviours which do not implement dynamic callbacks like ct_suite.
-define(KNOWN_BEHAVIOURS,
        [application,
         gen_event,
         gen_server,
         ssh_channel,
         ssh_client_channel,
         ssh_client_key_api,
         ssh_server_channel,
         ssh_server_key_api,
         ssl_crl_cache_api,
         ssl_session_cache_api,
         supervisor,
         supervisor_bridge,
         tftp]).

%% Allow erl_syntax:syntaxTree/0 type spec
%% Allow Module:behaviour_info/1 call
-elvis([{elvis_style, invalid_dynamic_call, disable},
        {elvis_style, atom_naming_convention, #{regex => "^([a-zA-Z][a-z0-9]*_?)*$"}}]).

-type imp_callbacks() :: #{File :: string() => [tuple()] | syntax_error}.

%% @private
-spec analyze(hank_rule:asts(), hank_context:t()) -> [hank_rule:result()].
analyze(FilesAndASTs, _Context) ->
    ImpCallbacks = callback_usage(FilesAndASTs),
    [Result
     || {File, AST} <- FilesAndASTs,
        not hank_utils:is_old_test_suite(File),
        is_parseable(File, ImpCallbacks),
        Node <- AST,
        erl_syntax:type(Node) == function,
        not is_exception_fun(hank_utils:function_tuple(Node)),
        not is_callback(Node, File, ImpCallbacks),
        Result <- analyze_function(File, Node)].

%% @doc Constructs a map with the callbacks of all the files.
%% 1. collect all the behaviors that the file implements.
%% 2. for each one of them, build the list of their possible callbacks.
%% 3. if that list could not be built (usually because of macros), adds 'syntax_error' instead.
-spec callback_usage(hank_rule:asts()) -> imp_callbacks().
callback_usage(FilesAndASTs) ->
    lists:foldl(fun({File, AST}, Result) ->
                   FoldFun =
                       fun(Node, FileCallbacks) ->
                          case hank_utils:node_has_attrs(Node, [behaviour, behavior]) of
                              true ->
                                  FileCallbacks ++ behaviour_callbacks(Node, AST);
                              _ ->
                                  FileCallbacks
                          end
                       end,
                   ResultsForFile =
                       try
                           erl_syntax_lib:fold(FoldFun, [], erl_syntax:form_list(AST))
                       catch
                           syntax_error ->
                               syntax_error
                       end,
                   maps:put(File, ResultsForFile, Result)
                end,
                #{},
                FilesAndASTs).

%% @doc Returns the behaviour's callback list if the given behaviour Node is a "known behaviour",
%%      this means it is an OTP behaviour without "dynamic" callbacks.
%%      If this is not satisfied or the behaviour attribute contains a macro,
%%      this function returns the whole list of functions that exported from the file.
%%      That's because, for dynamic behaviors, any exported function can be the implementation
%%      of a callback.
-spec behaviour_callbacks(erl_syntax:syntaxTree(), erl_syntax:forms()) ->
                             [{atom(), non_neg_integer()}].
behaviour_callbacks(Node, AST) ->
    try erl_syntax_lib:analyze_wild_attribute(Node) of
        {_, BehaviourMod} ->
            case lists:member(BehaviourMod, ?KNOWN_BEHAVIOURS) of
                true ->
                    BehaviourMod:behaviour_info(callbacks);
                false ->
                    module_exports(AST)
            end
    catch
        _:syntax_error ->
            %% There is a macro, then return all its exports, just in case
            module_exports(AST)
    end.

-spec module_exports(erl_syntax:forms()) -> [{atom(), non_neg_integer()}].
module_exports(AST) ->
    FoldFun =
        fun(Node, {ExportAll, Exports, Functions} = Acc) ->
           case erl_syntax:type(Node) of
               attribute ->
                   try erl_syntax_lib:analyze_attribute(Node) of
                       {export, NewExports} ->
                           {ExportAll, Exports ++ NewExports, Functions};
                       {compile, Opts} ->
                           {ExportAll orelse has_export_all(Opts), Exports, Functions};
                       _ ->
                           Acc
                   catch
                       _:syntax_error ->
                           %% Probably macros, we can't parse this module
                           throw(syntax_error)
                   end;
               function ->
                   Function = erl_syntax_lib:analyze_function(Node),
                   {ExportAll, Exports, [Function | Functions]};
               _ ->
                   Acc
           end
        end,
    case erl_syntax_lib:fold(FoldFun, {false, [], []}, erl_syntax:form_list(AST)) of
        {true, _Exports, Functions} ->
            Functions;
        {false, Exports, _Functions} ->
            Exports
    end.

has_export_all(List) when is_list(List) ->
    lists:member(export_all, List);
has_export_all(export_all) ->
    true;
has_export_all(_Opt) ->
    false.

%% @doc It will check if arguments are ignored in all function clauses:
%%      [(_a, b, _c), (_x, b, c)]
%%      [[1, 0, 1], [1, 0, 0]] => [1, 0, 0] => warning 1st param!
%%      [(a, _b, c), (_, b, c)]
%%      [[0, 1, 0], [1, 0, 0]] => [0, 0, 0] => ok
analyze_function(File, Function) ->
    lists:foldl(fun(Result, Acc) ->
                   case set_result(File, Result) of
                       ok ->
                           Acc;
                       Error ->
                           [Error | Acc]
                   end
                end,
                [],
                check_function(Function)).

set_result(File, {error, Line, Text, IgnorePattern}) ->
    #{file => File,
      line => Line,
      text => Text,
      pattern => IgnorePattern};
set_result(_File, _) ->
    ok.

check_function(FunctionNode) ->
    Clauses = erl_syntax:function_clauses(FunctionNode),
    ComputedResults =
        lists:foldl(fun(Clause, Result) ->
                       case is_clause_a_nif_stub(Clause) of
                           true ->
                               Result; %% Discard NIF stubs!
                           false ->
                               Patterns = erl_syntax:clause_patterns(Clause),
                               ClausePatterns =
                                   [pattern_to_integer(Pattern) || Pattern <- Patterns],
                               check_unused_args(Result, ClausePatterns)
                       end
                    end,
                    [],
                    Clauses),
    check_computed_results(FunctionNode, ComputedResults).

%% @doc Checks if the last expression in a clause body applies erlang:nif_error/x
is_clause_a_nif_stub(Clause) ->
    LastClauseBodyNode =
        lists:last(
            erl_syntax:clause_body(Clause)),
    case hank_utils:application_node_to_mfa(LastClauseBodyNode) of
        {"erlang", "nif_error", _Args} ->
            true;
        _ ->
            false
    end.

%% @doc Checks if the given function node implements a callback
-spec is_callback(erl_syntax:syntaxTree(), string(), imp_callbacks()) -> boolean().
is_callback(FunctionNode, File, ImpCallbacks) ->
    lists:member(
        hank_utils:function_tuple(FunctionNode), maps:get(File, ImpCallbacks, [])).

%% @doc Allows exceptions for functions whose name and arity are known but are
%%      not associated with a given behaviour (e.g. parse_transform/2)
is_exception_fun({parse_transform, 2}) ->
    true;
is_exception_fun(_) ->
    false.

%% @doc Returns true if hank could parse the file.
%%      Otherwise the file is ignored and no warnings are reported for it
-spec is_parseable(string(), imp_callbacks()) -> boolean().
is_parseable(File, ImpCallbacks) ->
    maps:get(File, ImpCallbacks, []) =/= syntax_error.

%% @doc Computes position by position (multiply/and)
%%      Will be 1 only when an argument is unused over all the function clauses
check_unused_args([], Arguments) ->
    Arguments;
check_unused_args(Result, Arguments) ->
    lists:zipwith(fun(A, B) -> A * B end, Result, Arguments).

pattern_to_integer({var, _Line, ArgNameAtom}) ->
    is_arg_ignored(atom_to_list(ArgNameAtom));
pattern_to_integer(_) ->
    0.

is_arg_ignored("_") ->
    1;
is_arg_ignored("_" ++ _) ->
    1;
is_arg_ignored(_) ->
    0.

check_computed_results(FunctionNode, Results) ->
    {_, Errors} =
        lists:foldl(fun(Result, {ArgNum, Errors}) ->
                       NewErrors =
                           case Result of
                               0 ->
                                   Errors;
                               1 ->
                                   [set_error(FunctionNode, ArgNum) | Errors]
                           end,
                       {ArgNum + 1, NewErrors}
                    end,
                    {1, []},
                    Results),
    Errors.

set_error(FuncNode, ArgNum) ->
    Line = hank_utils:node_line(FuncNode),
    FuncDesc = hank_utils:function_description(FuncNode),
    Text = hank_utils:format_text("~ts doesn't need its #~p argument", [FuncDesc, ArgNum]),
    FuncName = hank_utils:function_name(FuncNode),
    IgnorePattern = {list_to_atom(FuncName), erl_syntax:function_arity(FuncNode), ArgNum},
    {error, Line, Text, IgnorePattern}.

%% @doc Rule ignore specifications. Example:
%%      <pre>
%%      -hank([{unnecessary_function_arguments,
%%               %% You can give a list of multiple specs or a single one
%%               [%% Will ignore any unused argument from ignore_me/2 within the module
%%                {ignore_me, 2},
%%                %% Will ignore the 2nd argument from ignore_me_too/3 within the module
%%                {ignore_me_too, 3, 2},
%%                %% Will ignore any unused argument from any ignore_me_again/x
%%                %% within the module (no matter the function arity)
%%                ignore_me_again]}]).
%%      </pre>
-spec ignored(hank_rule:ignore_pattern(), term()) -> boolean().
ignored(Pattern, Pattern) ->
    true;
ignored({FuncName, _, _}, FuncName) ->
    true;
ignored({FuncName, FuncArity, _}, {FuncName, FuncArity}) ->
    true;
ignored(_Pattern, _IgnoreSpec) ->
    false.