Quokka

Quokka is an Elixir formatter plugin that's combination of mix format and mix credo, except instead of telling you what's wrong, it just rewrites the code for you. Quokka is a fork of Styler that checks the Credo config to determine which rules to rewrite. Many common, non-controversial Credo style rules are rewritten automatically, while the controversial Credo style rules are rewritten based on your Credo configuration so you can customize your style.

WARNING {: .warning}

Quokka can change the behavior of your program!

In some cases, this can introduce bugs. It goes without saying, but look over your changes before committing to main :)

We recommend making changes in small chunks until all of the more dangerous changes has been safely committed to the codebase

Installation

Add :quokka as a dependency to your project's mix.exs:

def deps do
  [
    {:quokka, "~> 0.1", only: [:dev, :test], runtime: false},
  ]
end

Then add Quokka as a plugin to your .formatter.exs file

[
  plugins: [Quokka]
]

And that's it! Now when you run mix format you'll also get the benefits of Quokka's Stylish Stylings.

First Run

You may want to initially run Quokka in "newline fixes only" mode. This will only fix spacing issues, making future PRs much smaller and easier to digest. See the example in the configuration section if you wish to do this.

Speed: Expect the first run to take some time as Quokka rewrites violations of styles and bottlenecks on disk I/O. Subsequent formats will take noticeably less time.

Configuration

Quokka primarily relies on the configurations of .formatter.exs and Credo (if available). However, there are some Quokka specific options that can also be specified in .formatter.exs to fine tune your setup:

[
  plugins: [Quokka],
  quokka: [
    inefficient_function_rewrites: true | false,
    files: %{
      included: ["lib/", ...],
      excluded: ["lib/example.ex", ...]
    },
    only: [
      # Changes to blocks of code
      :blocks
      # Comment directives such as # quokka:sort
      | :comment_directives
      # Sorting config files
      | :configs
      # Minimizes function heads
      | :defs
      # Converts deprecations
      | :deprecations
      # SPECIAL CASE: excludes all modules and only does newline fixups
      | :line_length
      # Fixes for imports, aliases, etc.
      | :module_directives
      # Various fixes for pipes
      | :pipes
      # Inefficient function rewrites, large numbers get underscores, etc.
      # Basically anything that doesn't fit into the categories above
      | :single_node
    ],
    exclude: [
      :blocks
      | :comment_directives
      | :configs
      | :defs
      | :deprecations
      | :module_directives
      | :pipes
      | :single_node
    ],
    piped_function_exclusions: [:subquery, :"Repo.update", ...]
  ]
]

Option	Description	Default
:autosort	Sort all maps and/or defstructs in your codebase. Quokka will skip sort maps that have comments inside them, though sorting can still be forced with # quokka:sort.	[]
:files	Quokka gets files from .formatter.exs[:inputs]. However, in some cases you may need to selectively exclude/include files you wish to still run in mix format, but have different behavior with Quokka.	%{included: [], excluded: []} (all files included, none excluded)
:only	Only include the given modules. The special :line_length option excludes all changes except line length fixups.	[] (all modules included)
:exclude	Exclude the given modules. This is just a convenience function that filters from the :only list.	[] (all modules included)
:inefficient_function_rewrites	Rewrite inefficient functions to more efficient form	true
:piped_function_exclusions	Allows you to specify certain functions that won't be rewritten into a pipe. Particularly good for things like Ecto's subquery macro.	[]

Credo inspired rewrites

The power of Quokka comes from utilizing the opinions you've already made with Credo and going one step further to attempt rewriting them for you.

Below is a general overall of many Credo checks Quokka attempts to handle and some additional useful details such as links to detailed documentation and if the check can be configured further for fine tuning.

:controversial Credo checks {: .tip}

Quokka allows all :controversial Credo checks to be configurable. In many cases, a Credo check can also be disabled to prevent rewriting.

Credo.Check.Consistency

Credo Check	Rewrite Description	Documentation	Configurable
.MultiAliasImportRequireUse	Expands multi-alias/import statements	Directive Expansion
.ParameterPatternMatching	Enforces consistent parameter pattern matching	Parameter Pattern Matching

Credo.Check.Design

Credo Check	Rewrite Description	Documentation	Configurable
.AliasUsage	Extracts repeated aliases	Alias Lifting	✓

Credo.Check.Readability

Credo Check	Rewrite Description	Documentation	Configurable
.AliasOrder	Alphabetizes module directives	Module Directives	✓
.BlockPipe	(En|dis)ables piping into blocks	Pipe Chains	✓
.LargeNumbers	Formats large numbers with underscores	Number Formatting	✓
.MaxLineLength	Enforces maximum line length	Line Length	✓
.MultiAlias	Expands multi-alias statements	Module Directives	✓
.OneArityFunctionInPipe	Optimizes pipe chains with single arity functions	Pipe Chains
.ParenthesesOnZeroArityDefs	Enforces consistent function call parentheses	Function Calls	✓
.PipeIntoAnonymousFunctions	Optimizes pipes with anonymous functions	Pipe Chains
.PreferImplicitTry	Simplifies try expressions	Control Flow Macros
.SinglePipe	Optimizes pipe chains	Pipe Chains	✓
.StringSigils	Replaces strings with sigils	Strings to Sigils
.StrictModuleLayout	Enforces strict module layout	Module Directives	✓
.UnnecessaryAliasExpansion	Removes unnecessary alias expansions	Module Directives
.WithSingleClause	Simplifies with statements	Control Flow Macros

Credo.Check.Refactor

Credo Check	Rewrite Description	Documentation	Configurable
.CondStatements	Simplifies boolean expressions	Control Flow Macros
.FilterCount	Optimizes filter + count operations	Styles
.MapInto	Optimizes map + into operations	Styles
.MapJoin	Optimizes map + join operations	Styles
.NegatedConditionsInUnless	Simplifies negated conditions in unless	Control Flow Macros
.NegatedConditionsWithElse	Simplifies negated conditions with else	Control Flow Macros
.PipeChainStart	Optimizes pipe chain start	Pipe Chains
.RedundantWithClauseResult	Removes redundant with clause results	Control Flow Macros
.UnlessWithElse	Simplifies unless with else	Control Flow Macros
.WithClauses	Optimizes with clauses	Control Flow Macros

License

Quokka is licensed under the Apache 2.0 license. See the LICENSE file for more details.