Adding Custom Checks

There comes a time when Credo does not feature the check you need or where you want to test a project- or domain-specific aspect of your codebase.

This is when you should consider implementing a Custom Check.

Custom checks are simply modules implementing the Credo.Check behaviour, which most of the time means that it is a module with a run/2 function returning a list of Credo.Issue structs:

# lib/checks/my_check.ex
defmodule MyProject.Checks.MyCheck do
  use Credo.Check

  def run(%SourceFile{} = source_file, params) do
    #
  end
end

Check Credo.Check for more technical information.

Our first check: Policing module attributes

Sometimes the conventions for names of module attributes change within a development team and you want to encourage people to stop using the old naming scheme for module attributes to avoid endless bikeshedding about whether or not the new naming policy was needed in the first place.

So, let's implement a check for this completely made up scenario!

Minimal check & config

First, we add the necessary Elixir module for the check and, for now, just return an empty list of issues.

# lib/my_project/checks/reject_module_attributes.ex
defmodule MyProject.Checks.RejectModuleAttributes do
  # Set up the behaviour and make this module a "check":
  use Credo.Check

  # The minimum each check has to implement is a `run/2` function which returns the found issues:
  def run(source_file, params \\ []) do
    []
  end
end

To run our new check, we also need to add the necessary :requires and :checks in our Credo config file:

# .credo.exs
%{
  configs: [
    %{
      name: "default",
      requires: ["./lib/my_project/checks/**/*.ex"],
      checks: [
        {MyProject.Checks.RejectModuleAttributes, []}
      ]
    }
  ]
}

This tells Credo to require all files in our checks directory and to enable the RejectModuleAttributes check.

Getting it working

For a first implementation, our check should look into all modules and report "violations" against a list of rejected names.

# lib/my_project/checks/reject_module_attributes.ex
defmodule MyProject.Checks.RejectModuleAttributes do
  use Credo.Check

  # Let's say we want to report module attributes named `@checkdoc`
  @rejected_names [:checkdoc]

  def run(source_file, params \\ []) do
    # IssueMeta helps keeping track of the source file and the check's params
    # (technically, it's just a custom tagged tuple)
    issue_meta = IssueMeta.for(source_file, params)

    # we'll walk the `source_file`'s AST and look for module attributes matching `@rejected_names`
    Credo.Code.prewalk(source_file, &traverse(&1, &2, @rejected_names, issue_meta))
  end

  # This matches on the AST structure of module attributes.
  defp traverse({:@, _, [{name, meta, [_string]} | _]} = ast, issues, rejected_names, issue_meta) do
    if Enum.member?(rejected_names, name) do
      {ast, issues ++ [issue_for(name, meta[:line], issue_meta)]}
    else
      {ast, issues}
    end
  end

  # For all AST nodes not matching the pattern above, we simply do nothing:
  defp traverse(ast, issues, _rejected_names, _issue_meta) do
    {ast, issues}
  end

  defp issue_for(trigger, line_no, issue_meta) do
    format_issue(
      issue_meta,
      message: "There should be no `@#{trigger}` module attributes.",
      trigger: "@#{trigger}",
      line_no: line_no
    )
  end
end

Traversal of the AST is done via Credo.Code.prewalk/2, which is a light wrapper around Macro.prewalk/3, taking a Credo.SourceFile struct instead of an AST.

You can use Code.string_to_quoted!/1 to look at the AST structure for code snippets:

iex> Code.string_to_quoted!("@my_attribute 23")
{:@, [line: 1], [{:my_attribute, [line: 1], [23]}]}

Adding configuration parameters

Next, we should have a config parameter which allows us to define which module attribute names are no longer allowed.

defmodule MyProject.Checks.RejectModuleAttributes do
  # To add a parameter, we use the `:param_defaults` keyword with `use Credo.Check`:
  use Credo.Check, param_defaults: [reject: [:checkdoc]]

  def run(source_file, params \\ []) do
    # To get a parameter, we use `Params.get/3`, which returns the given parameter from the config
    # or the default we registered above:
    reject = Params.get(params, :reject, __MODULE__)
    issue_meta = IssueMeta.for(source_file, params)

    Credo.Code.prewalk(source_file, &traverse(&1, &2, reject, issue_meta))
  end

  # ...
end

We can now use .credo.exs to configure the :reject param.

If the param is not declared ...

{MyProject.Checks.RejectModuleAttributes, []}

... then the default from your check is used.

If the param is declared, it overwrites the default, meaning that this ...

{MyProject.Checks.RejectModuleAttributes, [reject: [:shortdoc]]}

... forbids @shortdoc, but allows @checkdoc again.

Our final .credo.exs might look something like this:

# .credo.exs
%{
  configs: [
    %{
      name: "default",
      requires: ["./lib/my_project/checks/**/*.ex"],
      checks: [
        {MyProject.Checks.RejectModuleAttributes, [reject: [:checkdoc, :other_attr]]}
      ]
    }
  ]
}

Finalizing the check

To really make this a full-fledged Credo check, we have to configure its priority, category and describe what it does (you can find a description of the options in Credo.Check).

defmodule MyProject.Checks.RejectModuleAttributes do
  use Credo.Check,
    base_priority: :high,
    category: :readability,
    param_defaults: [reject: []],
    explanations: [
      check: """
      Look, sometimes the policies for names of module attributes change.
      We want to make sure that all module attributes adhere to the newest standards of ACME Corp.

      We do not want to discuss this policy, we just want to stop you from using the old
      module attributes :)
      """,
      params: [reject: "This check warns about module attributes with any of the given names."]
    ]

  # ...
end

You can now use Credo's explain command ...

$ mix credo explain MyProject.Checks.RejectModuleAttributes

... to show a description of your new check:

  MyProject.Checks.MyIExPry
┃
┃   [R] Category: readability
┃    ↗  Priority: high
┃
┃    __ WHY IT MATTERS
┃
┃       Look, sometimes the policies for names of module attributes change.
┃       We want to make sure that all module attributes adhere to the newest standards of ACME Corp.
┃
┃       We do not want to discuss this policy, we just want to stop you from using the old
┃       module attributes :)
┃
┃    __ CONFIGURATION OPTIONS
┃
┃       To configure this check, use this tuple
┃
┃         {MyProject.Checks.RejectModuleAttributes, <params>}
┃
┃       with <params> being false or any combination of these keywords:
┃
┃         reject:                Names of module attributes that are no longer allowed
┃                                (defaults to [])
┃

And that's it. Here's the final check:

defmodule MyProject.Checks.RejectModuleAttributes do
  use Credo.Check,
    base_priority: :high,
    category: :readability,
    param_defaults: [reject: []],
    explanations: [
      check: """
      Look, sometimes the policies for names of module attributes change.
      We want to make sure that all module attributes adhere to the newest standards of ACME Corp.

      We do not want to discuss this policy, we just want to stop you from using the old
      module attributes :)
      """,
      params: [reject: "Names of module attributes that are no longer allowed"]
    ]

  def run(source_file, params \\ []) do
    reject = Params.get(params, :reject, __MODULE__)

    issue_meta = IssueMeta.for(source_file, params)

    Credo.Code.prewalk(source_file, &traverse(&1, &2, reject, issue_meta))
  end

  defp traverse({:@, _, [{name, meta, [_string]} | _]} = ast, issues, rejected_names, issue_meta) do
    if Enum.member?(rejected_names, name) do
      {ast, issues ++ issue_for(name, meta[:line], issue_meta)}
    else
      {ast, issues}
    end
  end

  defp traverse(ast, issues, _rejected_names, _issue_meta) do
    {ast, issues}
  end

  defp issue_for(trigger, line_no, issue_meta) do
    format_issue(
      issue_meta,
      message: "There should be no `@#{trigger}` module attributes.",
      trigger: trigger,
      line_no: line_no
    )
  end
end

Next, let's see how we can write tests for our custom check!