zf

check.ex (19610B)

---

 defmodule Credo.Check do
   @moduledoc """
   `Check` modules represent the checks which are run during Credo's analysis.
 
   Example:
 
       defmodule MyCheck do
         use Credo.Check, category: :warning, base_priority: :high
 
         def run(%SourceFile{} = source_file, params) do
           #
         end
       end
 
   The check can be configured by passing the following
   options to `use Credo.Check`:
 
   - `:base_priority`  Sets the checks's base priority (`:low`, `:normal`, `:high`, `:higher` or `:ignore`).
   - `:category`       Sets the check's category (`:consistency`, `:design`, `:readability`, `:refactor`  or `:warning`).
   - `:elixir_version` Sets the check's version requirement for Elixir (defaults to `>= 0.0.1`).
   - `:explanations`   Sets explanations displayed for the check, e.g.
 
       ```elixir
       [
         check: "...",
         params: [
           param1: "Your favorite number",
           param2: "Online/Offline mode"
         ]
       ]
       ```
 
   - `:param_defaults` Sets the default values for the check's params (e.g. `[param1: 42, param2: "offline"]`)
   - `:tags`           Sets the tags for this check (list of atoms, e.g. `[:tag1, :tag2]`)
 
   Please also note that these options to `use Credo.Check` are just a convenience to implement the `Credo.Check`
   behaviour. You can implement any of these by hand:
 
       defmodule MyCheck do
         use Credo.Check
 
         def category, do: :warning
 
         def base_priority, do: :high
 
         def explanations do
           [
             check: "...",
             params: [
               param1: "Your favorite number",
               param2: "Online/Offline mode"
             ]
           ]
         end
 
         def param_defaults, do: [param1: 42, param2: "offline"]
 
         def run(%SourceFile{} = source_file, params) do
           #
         end
       end
 
   The `run/2` function of a Check module takes two parameters: a source file and a list of parameters for the check.
   It has to return a list of found issues.
   """
 
   @doc """
   Runs the current check on all `source_files` by calling `run_on_source_file/3`.
 
   If you are developing a check that has to run on all source files, you can overwrite `run_on_all_source_files/3`:
 
       defmodule MyCheck do
         use Credo.Check
 
         def run_on_all_source_files(exec, source_files, params) do
           issues =
             source_files
             |> do_something_crazy()
             |> do_something_crazier()
 
           append_issues_and_timings(exec, issues)
 
           :ok
         end
       end
 
   Check out Credo's checks from the consistency category for examples of these kinds of checks.
   """
   @callback run_on_all_source_files(
               exec :: Credo.Execution.t(),
               source_files :: list(Credo.SourceFile.t()),
               params :: Keyword.t()
             ) :: :ok
 
   @doc """
   Runs the current check on a single `source_file` and appends the resulting issues to the current `exec`.
   """
   @callback run_on_source_file(
               exec :: Credo.Execution.t(),
               source_file :: Credo.SourceFile.t(),
               params :: Keyword.t()
             ) :: :ok
 
   @callback run(source_file :: Credo.SourceFile.t(), params :: Keyword.t()) ::
               list(Credo.Issue.t())
 
   @doc """
   Returns the base priority for the check.
 
   This can be one of `:higher`, `:high`, `:normal`, `:low` or `:ignore`
   (technically it can also be  or an integer, but these are internal representations although that is not recommended).
   """
   @callback base_priority() :: :higher | :high | :normal | :low | :ignore | integer
 
   @doc """
   Returns the category for the check.
   """
   @callback category() :: atom
 
   @doc """
   Returns the required Elixir version for the check.
   """
   @callback elixir_version() :: String.t()
 
   @doc """
   Returns the exit status for the check.
   """
   @callback exit_status() :: integer
 
   @doc """
   Returns the explanations for the check and params as a keyword list.
   """
   @callback explanations() :: Keyword.t()
 
   @doc """
   Returns the default values for the check's params as a keyword list.
   """
   @callback param_defaults() :: Keyword.t()
 
   # @callback run(source_file :: Credo.SourceFile.t, params :: Keyword.t) :: list()
 
   @doc """
   Returns whether or not this check runs on all source files.
   """
   @callback run_on_all?() :: boolean
 
   @doc """
   Returns the tags for the check.
   """
   @callback tags() :: list(atom)
 
   @doc false
   @callback format_issue(issue_meta :: Credo.IssueMeta.t(), opts :: Keyword.t()) ::
               Credo.Issue.t()
 
   @base_category_exit_status_map %{
     consistency: 1,
     design: 2,
     readability: 4,
     refactor: 8,
     warning: 16
   }
 
   alias Credo.Check
   alias Credo.Check.Params
   alias Credo.Code.Scope
   alias Credo.Issue
   alias Credo.IssueMeta
   alias Credo.Priority
   alias Credo.Service.SourceFileScopes
   alias Credo.Severity
   alias Credo.SourceFile
 
   @valid_use_opts [
     :base_priority,
     :category,
     :elixir_version,
     :exit_status,
     :explanations,
     :param_defaults,
     :run_on_all,
     :tags
   ]
 
   @doc false
   defmacro __using__(opts) do
     Enum.each(opts, fn
       {key, _name} when key not in @valid_use_opts ->
         raise "Could not find key `#{key}` in #{inspect(@valid_use_opts)}"
 
       _ ->
         nil
     end)
 
     def_base_priority =
       if opts[:base_priority] do
         quote do
           @impl true
           def base_priority, do: unquote(opts[:base_priority])
         end
       else
         quote do
           @impl true
           def base_priority, do: 0
         end
       end
 
     def_category =
       if opts[:category] do
         quote do
           @impl true
           def category, do: unquote(category_body(opts[:category]))
         end
       else
         quote do
           @impl true
           def category, do: unquote(category_body(nil))
         end
       end
 
     def_elixir_version =
       if opts[:elixir_version] do
         quote do
           @impl true
           def elixir_version do
             unquote(opts[:elixir_version])
           end
         end
       else
         quote do
           @impl true
           def elixir_version, do: ">= 0.0.1"
         end
       end
 
     def_exit_status =
       if opts[:exit_status] do
         quote do
           @impl true
           def exit_status do
             unquote(opts[:exit_status])
           end
         end
       else
         quote do
           @impl true
           def exit_status, do: Credo.Check.to_exit_status(category())
         end
       end
 
     def_run_on_all? =
       if opts[:run_on_all] do
         quote do
           @impl true
           def run_on_all?, do: unquote(opts[:run_on_all] == true)
         end
       else
         quote do
           @impl true
           def run_on_all?, do: false
         end
       end
 
     def_param_defaults =
       if opts[:param_defaults] do
         quote do
           @impl true
           def param_defaults, do: unquote(opts[:param_defaults])
         end
       end
 
     def_explanations =
       if opts[:explanations] do
         quote do
           @impl true
           def explanations do
             unquote(opts[:explanations])
           end
         end
       end
 
     def_tags =
       quote do
         @impl true
         def tags do
           unquote(opts[:tags] || [])
         end
       end
 
     quote do
       @moduledoc unquote(moduledoc(opts))
       @behaviour Credo.Check
       @before_compile Credo.Check
 
       @use_deprecated_run_on_all? false
 
       alias Credo.Check
       alias Credo.Check.Params
       alias Credo.CLI.ExitStatus
       alias Credo.CLI.Output.UI
       alias Credo.Execution
       alias Credo.Execution.ExecutionTiming
       alias Credo.Issue
       alias Credo.IssueMeta
       alias Credo.Priority
       alias Credo.Severity
       alias Credo.SourceFile
 
       unquote(def_base_priority)
       unquote(def_category)
       unquote(def_elixir_version)
       unquote(def_exit_status)
       unquote(def_run_on_all?)
       unquote(def_param_defaults)
       unquote(def_explanations)
       unquote(def_tags)
 
       @impl true
       def format_issue(issue_meta, issue_options) do
         Check.format_issue(
           issue_meta,
           issue_options,
           __MODULE__
         )
       end
 
       @doc false
       @impl true
       def run_on_all_source_files(exec, source_files, params \\ [])
 
       @impl true
       def run_on_all_source_files(exec, source_files, params) do
         if function_exported?(__MODULE__, :run, 3) do
           IO.warn(
             "Defining `run(source_files, exec, params)` for checks that run on all source files is deprecated. " <>
               "Define `run_on_all_source_files(exec, source_files, params)` instead."
           )
 
           apply(__MODULE__, :run, [source_files, exec, params])
         else
           do_run_on_all_source_files(exec, source_files, params)
         end
       end
 
       defp do_run_on_all_source_files(exec, source_files, params) do
         source_files
         |> Enum.map(&Task.async(fn -> run_on_source_file(exec, &1, params) end))
         |> Enum.each(&Task.await(&1, :infinity))
 
         :ok
       end
 
       @doc false
       @impl true
       def run_on_source_file(exec, source_file, params \\ [])
 
       def run_on_source_file(%Execution{debug: true} = exec, source_file, params) do
         ExecutionTiming.run(&do_run_on_source_file/3, [exec, source_file, params])
         |> ExecutionTiming.append(exec,
           task: exec.current_task,
           check: __MODULE__,
           filename: source_file.filename
         )
       end
 
       def run_on_source_file(exec, source_file, params) do
         do_run_on_source_file(exec, source_file, params)
       end
 
       defp do_run_on_source_file(exec, source_file, params) do
         issues =
           try do
             run(source_file, params)
           rescue
             error ->
               UI.warn("Error while running #{__MODULE__} on #{source_file.filename}")
 
               if exec.crash_on_error do
                 reraise error, __STACKTRACE__
               else
                 []
               end
           end
 
         append_issues_and_timings(issues, exec)
 
         :ok
       end
 
       @doc false
       @impl true
       def run(source_file, params)
 
       def run(%SourceFile{} = source_file, params) do
         throw("Implement me")
       end
 
       defoverridable Credo.Check
 
       defp append_issues_and_timings([] = _issues, exec) do
         exec
       end
 
       defp append_issues_and_timings([_ | _] = issues, exec) do
         Credo.Execution.ExecutionIssues.append(exec, issues)
       end
     end
   end
 
   @doc false
   defmacro __before_compile__(env) do
     quote do
       unquote(deprecated_def_default_params(env))
       unquote(deprecated_def_explanations(env))
 
       @doc false
       def param_names do
         Keyword.keys(param_defaults())
       end
 
       @deprecated "Use param_defaults/1 instead"
       @doc false
       def params_defaults do
         # deprecated - remove module attribute
         param_defaults()
       end
 
       @deprecated "Use param_names/1 instead"
       @doc false
       def params_names do
         param_names()
       end
 
       @deprecated "Use explanations()[:check] instead"
       @doc false
       def explanation do
         # deprecated - remove module attribute
         explanations()[:check]
       end
 
       @deprecated "Use explanations()[:params] instead"
       @doc false
       def explanation_for_params do
         # deprecated - remove module attribute
         explanations()[:params]
       end
     end
   end
 
   defp moduledoc(opts) do
     explanations = opts[:explanations]
 
     base_priority = opts_to_string(opts[:base_priority]) || 0
 
     # category = opts_to_string(opts[:category]) || to_string(__MODULE__)
 
     elixir_version_hint =
       if opts[:elixir_version] do
         elixir_version = opts_to_string(opts[:elixir_version])
 
         "requires Elixir `#{elixir_version}`"
       else
         "works with any version of Elixir"
       end
 
     check_doc = opts_to_string(explanations[:check])
     params = explanations[:params] |> opts_to_string() |> List.wrap()
     param_defaults = opts_to_string(opts[:param_defaults])
 
     params_doc =
       if params == [] do
         "*There are no specific parameters for this check.*"
       else
         param_explanation =
           Enum.map(params, fn {key, value} ->
             default_value = inspect(param_defaults[key], limit: :infinity)
 
             default_hint =
               if default_value do
                 "*This parameter defaults to* `#{default_value}`."
               end
 
             value = value |> String.split("\n") |> Enum.map_join("\n", &"  #{&1}")
 
             """
             ### `:#{key}`
 
             #{value}
 
             #{default_hint}
 
             """
           end)
 
         """
         Use the following parameters to configure this check:
 
         #{param_explanation}
 
         """
       end
 
     """
     This check has a base priority of `#{base_priority}` and #{elixir_version_hint}.
 
     ## Explanation
 
     #{check_doc}
 
     ## Check-Specific Parameters
 
     #{params_doc}
 
     ## General Parameters
 
     Like with all checks, [general params](check_params.html) can be applied.
 
     Parameters can be configured via the [`.credo.exs` config file](config_file.html).
     """
   end
 
   defp opts_to_string(value) do
     {result, _} =
       value
       |> Macro.to_string()
       |> Code.eval_string()
 
     result
   end
 
   defp deprecated_def_default_params(env) do
     default_params = Module.get_attribute(env.module, :default_params)
 
     if is_nil(default_params) do
       if not Module.defines?(env.module, {:param_defaults, 0}) do
         quote do
           @impl true
           def param_defaults, do: []
         end
       end
     else
       # deprecated - remove once we ditch @default_params
       quote do
         @impl true
         def param_defaults do
           @default_params
         end
       end
     end
   end
 
   defp deprecated_def_explanations(env) do
     defines_deprecated_explanation_module_attribute? =
       !is_nil(Module.get_attribute(env.module, :explanation))
 
     defines_deprecated_explanations_fun? = Module.defines?(env.module, {:explanations, 0})
 
     if defines_deprecated_explanation_module_attribute? do
       # deprecated - remove once we ditch @explanation
       quote do
         @impl true
         def explanations do
           @explanation
         end
       end
     else
       if !defines_deprecated_explanations_fun? do
         quote do
           @impl true
           def explanations, do: []
         end
       end
     end
   end
 
   def explanation_for(nil, _), do: nil
   def explanation_for(keywords, key), do: keywords[key]
 
   @doc """
   format_issue takes an issue_meta and returns an issue.
   The resulting issue can be made more explicit by passing the following
   options to `format_issue/2`:
 
   - `:priority`     Sets the issue's priority.
   - `:trigger`      Sets the issue's trigger.
   - `:line_no`      Sets the issue's line number. Tries to find `column` if `:trigger` is supplied.
   - `:column`       Sets the issue's column.
   - `:exit_status`  Sets the issue's exit_status.
   - `:severity`     Sets the issue's severity.
   """
   def format_issue(issue_meta, opts, check) do
     params = IssueMeta.params(issue_meta)
     issue_category = Params.category(params, check)
     issue_base_priority = Params.priority(params, check)
 
     format_issue(issue_meta, opts, issue_category, issue_base_priority, check)
   end
 
   @doc false
   def format_issue(issue_meta, opts, issue_category, issue_priority, check) do
     source_file = IssueMeta.source_file(issue_meta)
     params = IssueMeta.params(issue_meta)
 
     priority = Priority.to_integer(issue_priority)
 
     exit_status_or_category = Params.exit_status(params, check) || issue_category
     exit_status = Check.to_exit_status(exit_status_or_category)
 
     line_no = opts[:line_no]
     trigger = opts[:trigger]
     column = opts[:column]
     severity = opts[:severity] || Severity.default_value()
 
     %Issue{
       priority: priority,
       filename: source_file.filename,
       message: opts[:message],
       trigger: trigger,
       line_no: line_no,
       column: column,
       severity: severity,
       exit_status: exit_status
     }
     |> add_line_no_options(line_no, source_file)
     |> add_column_if_missing(trigger, line_no, column, source_file)
     |> add_check_and_category(check, issue_category)
   end
 
   defp add_check_and_category(issue, check, issue_category) do
     %Issue{
       issue
       | check: check,
         category: issue_category
     }
   end
 
   defp add_column_if_missing(issue, trigger, line_no, column, source_file) do
     if trigger && line_no && !column do
       %Issue{
         issue
         | column: SourceFile.column(source_file, line_no, trigger)
       }
     else
       issue
     end
   end
 
   defp add_line_no_options(issue, line_no, source_file) do
     if line_no do
       {_def, scope} = scope_for(source_file, line: line_no)
 
       %Issue{
         issue
         | priority: issue.priority + priority_for(source_file, scope),
           scope: scope
       }
     else
       issue
     end
   end
 
   # Returns the scope for the given line as a tuple consisting of the call to
   # define the scope (`:defmodule`, `:def`, `:defp` or `:defmacro`) and the
   # name of the scope.
   #
   # Examples:
   #
   #     {:defmodule, "Foo.Bar"}
   #     {:def, "Foo.Bar.baz"}
   #
   @doc false
   def scope_for(source_file, line: line_no) do
     source_file
     |> scope_list
     |> Enum.at(line_no - 1)
   end
 
   # Returns all scopes for the given source_file per line of source code as tuple
   # consisting of the call to define the scope
   # (`:defmodule`, `:def`, `:defp` or `:defmacro`) and the name of the scope.
   #
   # Examples:
   #
   #     [
   #       {:defmodule, "Foo.Bar"},
   #       {:def, "Foo.Bar.baz"},
   #       {:def, "Foo.Bar.baz"},
   #       {:def, "Foo.Bar.baz"},
   #       {:def, "Foo.Bar.baz"},
   #       {:defmodule, "Foo.Bar"}
   #     ]
   defp scope_list(%SourceFile{} = source_file) do
     case SourceFileScopes.get(source_file) do
       {:ok, value} ->
         value
 
       :notfound ->
         ast = SourceFile.ast(source_file)
         lines = SourceFile.lines(source_file)
         scope_info_list = Scope.scope_info_list(ast)
 
         result =
           Enum.map(lines, fn {line_no, _} ->
             Scope.name_from_scope_info_list(scope_info_list, line_no)
           end)
 
         SourceFileScopes.put(source_file, result)
 
         result
     end
   end
 
   defp priority_for(source_file, scope) do
     scope_prio_map = Priority.scope_priorities(source_file)
 
     scope_prio_map[scope] || 0
   end
 
   defp category_body(nil) do
     quote do
       name =
         __MODULE__
         |> Module.split()
         |> Enum.at(2)
 
       safe_name = name || :unknown
 
       safe_name
       |> to_string
       |> String.downcase()
       |> String.to_atom()
     end
   end
 
   defp category_body(value), do: value
 
   @doc "Converts a given category to an exit status"
   def to_exit_status(nil), do: 0
 
   def to_exit_status(atom) when is_atom(atom) do
     to_exit_status(@base_category_exit_status_map[atom])
   end
 
   def to_exit_status(value) when is_number(value), do: value
 
   @doc false
   def defined?(check)
 
   def defined?({atom, _params}), do: defined?(atom)
 
   def defined?(binary) when is_binary(binary) do
     binary |> String.to_atom() |> defined?()
   end
 
   def defined?(module) when is_atom(module) do
     case Code.ensure_compiled(module) do
       {:module, _} -> true
       {:error, _} -> false
     end
   end
 end