View Source Credo.Check behaviour (Credo v1.7.2-rc.4)

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.

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

Summary

Callbacks

Returns the base priority for the check.

Returns the category for the check.

Returns the docs URL for the check.

Returns the required Elixir version for the check.

Returns the exit status for the check.

Returns the explanations for the check and params as a keyword list.

Returns an ID that can be used to identify the check.

Returns the default values for the check's params as a keyword list.

Returns whether or not this check runs on all source files.

Runs the current check on all source_files by calling run_on_source_file/3.

Runs the current check on a single source_file and appends the resulting issues to the current exec.

Returns the tags for the check.

Functions

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

Converts a given category to an exit status

Callbacks

@callback base_priority() :: :higher | :high | :normal | :low | :ignore | integer()

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 category() :: atom()

Returns the category for the check.

@callback docs_uri() :: binary()

Returns the docs URL for the check.

@callback elixir_version() :: String.t()

Returns the required Elixir version for the check.

@callback exit_status() :: integer()

Returns the exit status for the check.

@callback explanations() :: Keyword.t()

Returns the explanations for the check and params as a keyword list.

Link to this callback

format_issue(issue_meta, opts)

View Source
@callback format_issue(issue_meta :: Credo.IssueMeta.t(), opts :: Keyword.t()) ::
  Credo.Issue.t()
@callback id() :: binary()

Returns an ID that can be used to identify the check.

@callback param_defaults() :: Keyword.t()

Returns the default values for the check's params as a keyword list.

Link to this callback

run(source_file, params)

View Source
@callback run(source_file :: Credo.SourceFile.t(), params :: Keyword.t()) :: [
  Credo.Issue.t()
]
@callback run_on_all?() :: boolean()

Returns whether or not this check runs on all source files.

Link to this callback

run_on_all_source_files(exec, source_files, params)

View Source
@callback run_on_all_source_files(
  exec :: Credo.Execution.t(),
  source_files :: [Credo.SourceFile.t()],
  params :: Keyword.t()
) :: :ok

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.

Link to this callback

run_on_source_file(exec, source_file, params)

View Source
@callback run_on_source_file(
  exec :: Credo.Execution.t(),
  source_file :: Credo.SourceFile.t(),
  params :: Keyword.t()
) :: :ok

Runs the current check on a single source_file and appends the resulting issues to the current exec.

@callback tags() :: [atom()]

Returns the tags for the check.

Functions

Link to this function

explanation_for(keywords, key)

View Source
Link to this function

format_issue(issue_meta, opts, check)

View Source

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, i.e. the text causing the issue (see Credo.Check.Warning.IoInspect).
  • :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.

Converts a given category to an exit status