Tiny Robots Credo Checks

Highly opinionatedCredo checks used by Tiny Robots. They encode the Elixir / Phoenix / LiveView conventions we rely on across our apps.

These checks are opinionated by design — they enforce the Tiny Robots house style and may not be suitable (or desired) for contribution upstream to mainline Credo. They're published here so our projects can share them, but anyone sharing our conventions is welcome to use them.

Available checks

See the individual modules for full descriptions and examples. The recommended way to enable them is Rbtz.CredoChecks.all/0 — see Installation and configuration.

Design

• Rbtz.CredoChecks.Design.BareScriptInHeex: Forbids raw <script> tags in HEEx templates — use a phx-hook, the root layout, or import through the asset bundler.
• Rbtz.CredoChecks.Design.CnInClassList: Enforces correct use of the cn(...) class-merging helper in HEEx class={...} attributes — flags cn([...]) with no @assign (wasted), bare lists mixing literal classes with any caller-provided assign (unwrapped, so TwMerge can't dedupe), and cn(...) calls where assigns aren't listed last (TwMerge keeps the last value, so assigns before literals lose their override). Configurable via :helper_name (default "cn").
• Rbtz.CredoChecks.Design.CustomAliasInRouterScope: Forbids manual alias statements inside Phoenix scope blocks.
• Rbtz.CredoChecks.Design.PreferLogsterInLib: Forbids the standard Logger module in application code under lib/ — use Logster instead.
• Rbtz.CredoChecks.Design.RawHtmlElementsInHeex: Forbids raw <button>, <input>, <select>, <textarea>, and <a> in HEEx — use the app's components instead.
• Rbtz.CredoChecks.Design.RawSvgInHeex: Forbids raw <svg> tags in HEEx templates.

Readability

• Rbtz.CredoChecks.Readability.AtomHttpStatusCodes: Forbids passing integer HTTP status codes to Plug.Conn / Phoenix controllers and Phoenix.ConnTest assertion helpers (json_response, html_response, response, redirected_to) — use atoms like :not_found.
• Rbtz.CredoChecks.Readability.AwkwardPipe: Flags pipe usages that hurt readability without giving chaining benefit — pipe on either side of && / || / ++ / <> / in / and / or, pipes into any Kernel. operator form (e.g. Kernel.&& / Kernel.|| / Kernel.+ / Kernel.- / Kernel.== / Kernel.< / Kernel.in), single-step pipes in tuple literals / string interpolation / non-first arg positions / single-line lambdas, any pipe joined in an if / unless / cond condition, single-step pipes on the RHS of <- inside HEEx :for= / for comprehensions, and single-step pipes wrapped in parens just to dot-access their result.
• Rbtz.CredoChecks.Readability.ClassAttrFormatting: Enforces HEEx class={...} attributes use list syntax for multiple values, and flags any class-attribute line — single-line or inside a multi-line list — that exceeds :max_line_length (default 98).
• Rbtz.CredoChecks.Readability.LiveViewCallbackOrder: Enforces the canonical callback order in Phoenix.LiveView modules: mount → handle_params → handle_event → handle_info → handle_async → helpers → render.
• Rbtz.CredoChecks.Readability.ModuleAttrCollectionFormatting: Flags multi-line collections assigned to module attributes — word sigils (~w[...] / ~W[...]), lists, maps/structs, and tuples — that pack more than one item onto a line. Put one item per line so the collection is easy to scan, diff, and update. Single-line collections are unaffected, however many items they hold.
• Rbtz.CredoChecks.Readability.PreferBlockFormForMultilineIf: Forbids the keyword form if cond, do: x, else: y (and the unless equivalent) when the expression spans more than one line — switch to the do ... else ... end block form. Single-line keyword form is fine.
• Rbtz.CredoChecks.Readability.PreferBooleanDataAttrShorthand: Forbids data-[name]: bracket-variant syntax for boolean data attributes — use data-name: instead, reserving brackets for value matching (data-[state=open]:).
• Rbtz.CredoChecks.Readability.PreferCapture: Encourages the capture syntax (&foo/1, &Mod.foo/2, &(&1 * 2)) over fn x -> ... end when the anonymous function just forwards its arguments to another call in the same order, applies a single operator, or partially applies a call.
• Rbtz.CredoChecks.Readability.PreferNilEquality: Prefers x == nil / x != nil over is_nil(x) / not is_nil(x) in if / unless / cond / case conditions and in assert / refute arguments. is_nil/1 in when guards and Ecto query DSL is unaffected.
• Rbtz.CredoChecks.Readability.PreferSigilSForEscapedQuotes: Encourages the ~s sigil for strings that would otherwise need \" escapes.
• Rbtz.CredoChecks.Readability.PreferToTimeout: Encourages to_timeout(minute: 15) (Elixir 1.17+) over Erlang's :timer.seconds/1, :timer.minutes/1, :timer.hours/1, and :timer.hms/3.
• Rbtz.CredoChecks.Readability.RedundantClassAttrWrapping: Flags HEEx class={...} attributes whose wrapping is unnecessary — class={"foo"} / class={["foo"]} should be class="foo"; class={[expr]} should be class={expr}.
• Rbtz.CredoChecks.Readability.ShorthandDefMustBeCompact: Forbids the shorthand def name(args), do: body form whose body spans more than one line — switch to a do...end block when the body has to wrap. Multi-line heads (e.g. nested pattern matches) are fine as long as the body stays on a single line.
• Rbtz.CredoChecks.Readability.SnakeCaseVariableNumbering: Encourages numbered variables to use a separating underscore: user_1, user_2 (not user1, user2). Configurable via :exclude.
• Rbtz.CredoChecks.Readability.TopLevelAliasImportRequire: Ensures alias, import, and require statements appear only at the top level of a module.

Refactor

• Rbtz.CredoChecks.Refactor.PreferEctoMigrationHelper: Discourages raw SQL execute("...") in Ecto migrations when an equivalent migration helper exists (e.g. CREATE TABLE, ALTER TABLE, CREATE INDEX). Raw SQL for CREATE EXTENSION, data backfills, etc. is allowed.
• Rbtz.CredoChecks.Refactor.PreferForAttrOverForBlock: Prefers :for={item <- @collection} directly on an element over a <%= for ... do %> EEx block when the block wraps a single element.
• Rbtz.CredoChecks.Refactor.PreferTextColumns: Ensures Ecto migrations use :text rather than :string for column types.
• Rbtz.CredoChecks.Refactor.PreferToFormInTemplates: Forbids passing a raw @changeset to a <form> / <.form> in HEEx — wrap with to_form/2 and pass @form instead.
• Rbtz.CredoChecks.Refactor.RawHtmlMatchInLiveViewTests: Forbids =~ matches against string literals in LiveView test files.
• Rbtz.CredoChecks.Refactor.RedundantThen: Flags unnecessary uses of Kernel.then/2 — when the function passed to then/2 is a simple pass-through or partial application where the piped value already lands at the first-arg position, then/2 is pure indirection and can be removed.

Warning

• Rbtz.CredoChecks.Warning.AssertNonEmptyBeforeIterate: Requires tests that iterate a collection with assert/refute inside to first assert the collection is non-empty.
• Rbtz.CredoChecks.Warning.BooleanDataAttrCoalescesNil: Requires boolean data-* attributes in HEEx to coalesce with nil (e.g. data-disabled={@disabled || nil}) so the attribute is omitted when falsy.
• Rbtz.CredoChecks.Warning.DisableMigrationLock: Forbids @disable_migration_lock true in Ecto migration files.
• Rbtz.CredoChecks.Warning.EnumEachInHeex: Forbids <% Enum.each %> and other side-effecting EEx constructs in HEEx templates.
• Rbtz.CredoChecks.Warning.LiveViewFormCanBeRehydrated: Ensures LiveView forms (with phx-submit) also carry id and phx-change so state survives deploys and reconnects.
• Rbtz.CredoChecks.Warning.PhxClickAwayWithoutId: Requires every element with phx-click-away to also carry an id attribute.
• Rbtz.CredoChecks.Warning.PhxHookComponentWithoutStableId: Requires function components whose template uses phx-hook to bind the hook target to a stable DOM id — either a literal (id="foo") or id={@name} bound to an attr declared with required: true or a binary default:.
• Rbtz.CredoChecks.Warning.PhxHookWithoutId: Requires every element with phx-hook to also carry an id attribute.
• Rbtz.CredoChecks.Warning.PhxUpdateStreamWithoutId: Requires every element with phx-update="stream" to also carry an id attribute.
• Rbtz.CredoChecks.Warning.PreferGetFieldOnChangeset: Requires Ecto.Changeset.get_field/2 over changeset.field or changeset[:field] — direct access returns the original field, not the changeset's current (potentially changed) value, which is a frequent source of subtle bugs.
• Rbtz.CredoChecks.Warning.PushEventSocketBinding: Requires the result of push_event/3 to be reassigned to socket.
• Rbtz.CredoChecks.Warning.ReqTestWithoutVerifyOnExit: Requires test modules that mock HTTP with Req.Test.stub/expect to call Req.Test.verify_on_exit!/0 in a setup/setup_all block.
• Rbtz.CredoChecks.Warning.SetMimicGlobal: Forbids enabling Mimic in global mode (set_mimic_global) inside test files.
• Rbtz.CredoChecks.Warning.SortKeywordValidateResult: Requires Enum.sort/1 between Keyword.validate!/2 and any binding that pattern-matches the result — unsorted results can silently break pattern matches on keyword list order.
• Rbtz.CredoChecks.Warning.StringInterpolationInClassAttr: Forbids string interpolation inside HEEx class= attributes — Tailwind's static class extractor can't see interpolated classes, so they silently don't ship in the compiled CSS.
• Rbtz.CredoChecks.Warning.UnnamedOtpProcess: Requires DynamicSupervisor and Registry child specs to declare a :name.

Installation and configuration

1. Add rbtz_credo_checks to your mix.exs dependencies:

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

2. Run mix deps.get.

3. Enable the checks in your .credo.exs. The recommended way is Rbtz.CredoChecks.all/0, which returns every check as a {module, opts} tuple ready to append to your enabled: list. It stays in sync automatically as this library adds checks — there's nothing to hand-maintain:

   %{
     configs: [
       %{
         checks: %{
           enabled:
             [
               # ...your Credo built-in checks...
             ] ++ Rbtz.CredoChecks.all()
         }
       }
     ]
   }
   

Customising and disabling checks

Use Rbtz.CredoChecks.all_replacing/1 with a list of {module, opts} replacements. Each is matched by module name and replaces that check's options, leaving every other check untouched.

To customise a check's options, pass a keyword list:

Rbtz.CredoChecks.all_replacing([
  {Rbtz.CredoChecks.Readability.SnakeCaseVariableNumbering, exclude: ["utf8", "ipv4", "ipv6"]}
])

To disable a check, pass false as its options — Credo treats {check, false} as disabled, so the check stays in the list but is turned off:

Rbtz.CredoChecks.all_replacing([
  {Rbtz.CredoChecks.Design.PreferLogsterInLib, false}
])

You can combine both, and replacements naming a module that isn't one of these checks raise an ArgumentError, so typos surface immediately:

enabled:
  [
    # ...your Credo built-in checks...
  ] ++
    Rbtz.CredoChecks.all_replacing([
      {Rbtz.CredoChecks.Readability.SnakeCaseVariableNumbering, exclude: ["utf8", "ipv4", "ipv6"]},
      {Rbtz.CredoChecks.Design.PreferLogsterInLib, false}
    ])

Enabling checks individually

If you'd rather not enable everything, you can skip the helpers and list the checks by hand in your enabled: list. This is the full set Rbtz.CredoChecks.all/0 returns — drop any you don't want, and add a second tuple element to customise a check (or false to disable it):

enabled:
  [
    # ...your Credo built-in checks...

    {Rbtz.CredoChecks.Design.BareScriptInHeex, []},
    {Rbtz.CredoChecks.Design.CnInClassList, []},
    {Rbtz.CredoChecks.Design.CustomAliasInRouterScope, []},
    {Rbtz.CredoChecks.Design.PreferLogsterInLib, []},
    {Rbtz.CredoChecks.Design.RawHtmlElementsInHeex, []},
    {Rbtz.CredoChecks.Design.RawSvgInHeex, []},
    {Rbtz.CredoChecks.Readability.AtomHttpStatusCodes, []},
    {Rbtz.CredoChecks.Readability.AwkwardPipe, []},
    {Rbtz.CredoChecks.Readability.ClassAttrFormatting, []},
    {Rbtz.CredoChecks.Readability.LiveViewCallbackOrder, []},
    {Rbtz.CredoChecks.Readability.ModuleAttrCollectionFormatting, []},
    {Rbtz.CredoChecks.Readability.PreferBlockFormForMultilineIf, []},
    {Rbtz.CredoChecks.Readability.PreferBooleanDataAttrShorthand, []},
    {Rbtz.CredoChecks.Readability.PreferCapture, []},
    {Rbtz.CredoChecks.Readability.PreferNilEquality, []},
    {Rbtz.CredoChecks.Readability.PreferSigilSForEscapedQuotes, []},
    {Rbtz.CredoChecks.Readability.PreferToTimeout, []},
    {Rbtz.CredoChecks.Readability.RedundantClassAttrWrapping, []},
    {Rbtz.CredoChecks.Readability.ShorthandDefMustBeCompact, []},
    {Rbtz.CredoChecks.Readability.SnakeCaseVariableNumbering, []},
    {Rbtz.CredoChecks.Readability.TopLevelAliasImportRequire, []},
    {Rbtz.CredoChecks.Refactor.PreferEctoMigrationHelper, []},
    {Rbtz.CredoChecks.Refactor.PreferForAttrOverForBlock, []},
    {Rbtz.CredoChecks.Refactor.PreferTextColumns, []},
    {Rbtz.CredoChecks.Refactor.PreferToFormInTemplates, []},
    {Rbtz.CredoChecks.Refactor.RawHtmlMatchInLiveViewTests, []},
    {Rbtz.CredoChecks.Refactor.RedundantThen, []},
    {Rbtz.CredoChecks.Warning.AssertNonEmptyBeforeIterate, []},
    {Rbtz.CredoChecks.Warning.BooleanDataAttrCoalescesNil, []},
    {Rbtz.CredoChecks.Warning.DisableMigrationLock, []},
    {Rbtz.CredoChecks.Warning.EnumEachInHeex, []},
    {Rbtz.CredoChecks.Warning.LiveViewFormCanBeRehydrated, []},
    {Rbtz.CredoChecks.Warning.PhxClickAwayWithoutId, []},
    {Rbtz.CredoChecks.Warning.PhxHookComponentWithoutStableId, []},
    {Rbtz.CredoChecks.Warning.PhxHookWithoutId, []},
    {Rbtz.CredoChecks.Warning.PhxUpdateStreamWithoutId, []},
    {Rbtz.CredoChecks.Warning.PreferGetFieldOnChangeset, []},
    {Rbtz.CredoChecks.Warning.PushEventSocketBinding, []},
    {Rbtz.CredoChecks.Warning.ReqTestWithoutVerifyOnExit, []},
    {Rbtz.CredoChecks.Warning.SetMimicGlobal, []},
    {Rbtz.CredoChecks.Warning.SortKeywordValidateResult, []},
    {Rbtz.CredoChecks.Warning.StringInterpolationInClassAttr, []},
    {Rbtz.CredoChecks.Warning.UnnamedOtpProcess, []}
  ]

License

MIT. See LICENSE.