AshCredo

AshCredo is an unofficial set of static analysis checks for the Ash Framework, built as a Credo plugin.

AshCredo finds common anti-patterns, security pitfalls, and missing best practices in your Ash resources, domains, and the code that calls into them. Some checks analyse the unexpanded source AST. Others introspect the compiled modules and see the fully resolved DSL state, including anything Spark transformers and extensions contribute.

Only the following checks are enabled by default. All other checks are opt-in: enable them individually in your .credo.exs (see Configuration).

• Warning.CompileTimeDefault
• Warning.MissingBuiltinWrapper
• Warning.MissingMacroDirective
• Warning.PinnedTimeInExpression

Installation

AshCredo requires Credo to already be installed in your project.

With Igniter (recommended)

If your project uses Igniter, a single command adds the dependency and registers the plugin in your .credo.exs:

mix igniter.install ash_credo@0.17.1

The explicit version prevents Igniter from generating a broad pre-1.0 requirement. Igniter pins a three-part version exactly, so if you prefer compatible patch updates, use the manual requirement below. The installer scopes ash_credo to :dev/:test and sets runtime: false automatically, matching how credo itself is typically declared. Pass --only dev,test if you'd like an early error when running from another MIX_ENV.

Manual

Add ash_credo to your list of dependencies in mix.exs:

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

Then fetch the dependency and register the plugin in your .credo.exs:

mix deps.get

# .credo.exs
%{
  configs: [
    %{
      name: "default",
      plugins: [{AshCredo, []}]
    }
  ]
}

Running

mix credo

If you have any compiled-introspection checks enabled, run mix compile before mix credo, typically via a Mix alias like lint: ["compile", "credo --strict"]. See Checks that require a compiled project for the full list and the rationale.

Checks

Checks that require a compiled project

Several checks read Ash's runtime introspection (Ash.Resource.Info, Ash.Domain.Info, and Ash.Policy.Info) rather than the source AST. They see the fully resolved resource state, including anything Spark transformers or extensions contribute, and catch bugs that pure AST scanning would miss: identities on AshAuthentication-injected :email attributes, fragment-spliced actions, extension-added authorizers, and so on.

• Warning.AuthorizerWithoutPolicies
• Warning.MissingMacroDirective
• Warning.RedundantValidation
• Warning.UnknownAction
• Refactor.RaisingCall
• Refactor.UseCodeInterface
• Design.MissingCodeInterface
• Design.MissingIdentity
• Design.MissingPrimaryAction
• Design.MissingTimestamps

Compile your project before running mix credo. Otherwise these checks emit a configuration diagnostic and become a no-op. Typically you chain the two commands in a Mix alias:

# mix.exs
defp aliases do
  [
    lint: ["compile", "credo --strict"]
  ]
end

If a referenced resource can't be loaded, the check emits a per-call-site "could not load" issue pointing at the resource. If Ash itself isn't available in the VM running Credo, these checks emit a single shared diagnostic and become no-ops. You can disable any of them in .credo.exs if your workflow can't run mix compile beforehand.

Configuration

Enable additional checks by adding them to the extra section of your .credo.exs:

%{
  configs: [
    %{
      name: "default",
      plugins: [{AshCredo, []}],
      checks: %{
        extra: [
          # Enable checks
          {AshCredo.Check.Warning.AuthorizeFalse, []},
          {AshCredo.Check.Warning.SensitiveFieldInAccept, []},
          {AshCredo.Check.Warning.WildcardAcceptOnAction, []},

          # Enable with custom parameters
          {AshCredo.Check.Refactor.LargeResource, [max_lines: 250]},
          {AshCredo.Check.Warning.SensitiveAttributeExposed, [
            sensitive_names: ~w(password token secret api_key)a
          ]},
          {AshCredo.Check.Design.MissingIdentity, [
            identity_candidates: ~w(email username slug)a
          ]}
        ]
      }
    }
  ]
}

To enable all checks at once (the default-on checks listed above don't need an entry):

checks: %{
  extra: [
    {AshCredo.Check.Warning.ActorOnCallOptions, []},
    {AshCredo.Check.Warning.AuthorizeFalse, []},
    {AshCredo.Check.Warning.AuthorizerWithoutPolicies, []},
    {AshCredo.Check.Warning.EmptyDomain, []},
    {AshCredo.Check.Warning.MissingDomain, []},
    {AshCredo.Check.Warning.OverlyPermissivePolicy, []},
    {AshCredo.Check.Warning.RedundantValidation, []},
    {AshCredo.Check.Warning.SensitiveAttributeExposed, []},
    {AshCredo.Check.Warning.SensitiveFieldInAccept, []},
    {AshCredo.Check.Warning.UnknownAction, []},
    {AshCredo.Check.Warning.WildcardAcceptOnAction, []},
    {AshCredo.Check.Refactor.AnonymousFunctionInDsl, []},
    {AshCredo.Check.Refactor.DirectiveInFunctionBody, []},
    {AshCredo.Check.Refactor.LargeResource, []},
    {AshCredo.Check.Refactor.RaisingCall, []},
    {AshCredo.Check.Refactor.UseCodeInterface, []},
    {AshCredo.Check.Design.MissingCodeInterface, []},
    {AshCredo.Check.Design.MissingIdentity, []},
    {AshCredo.Check.Design.MissingPrimaryAction, []},
    {AshCredo.Check.Design.MissingTimestamps, []},
    {AshCredo.Check.Readability.ActionMissingDescription, []},
    {AshCredo.Check.Readability.BelongsToMissingAllowNil, []}
  ]
}

Configurable parameters

The following checks accept custom parameters:

Adapting UseCodeInterface to your team's conventions

UseCodeInterface accepts params that map to common code-interface philosophies. The two enforce_* flags decide which call sites the check fires on; prefer_interface_scope decides which interface the suggestion points at. They compose freely.

# Default: an in-domain caller gets the resource interface.
# An outside-domain caller gets the domain interface.
{AshCredo.Check.Refactor.UseCodeInterface, []},

# Opinion A: raw Ash.* calls are OK when the caller is in the resource's
# domain (e.g. inside a Change / Preparation / Validation module). Only
# flag callers from outside the domain.
{AshCredo.Check.Refactor.UseCodeInterface,
 [enforce_code_interface_in_domain: false]},

# Opinion B: code interfaces are only defined on resources. Never suggest
# reaching for a domain-level interface, regardless of the call site.
{AshCredo.Check.Refactor.UseCodeInterface,
 [prefer_interface_scope: :resource]},

# Opinion C: the inverse of Opinion A. Strict inside the domain (changes,
# preparations, validations, sibling resources must use code interfaces),
# but permissive outside (controllers, LiveViews, workers can call Ash.*
# directly without a nag). Useful for incremental adoption: enforce the
# pattern in the resource layer first, clean up the web layer later.
{AshCredo.Check.Refactor.UseCodeInterface,
 [enforce_code_interface_outside_domain: false]},

# Opinion A + B: allow same-domain raw calls AND always direct the rest
# at the resource-level interface.
{AshCredo.Check.Refactor.UseCodeInterface,
 [enforce_code_interface_in_domain: false, prefer_interface_scope: :resource]},

• enforce_code_interface_in_domain (default true). When false, the check leaves callers that share a domain with the resource alone (Opinion A).
• enforce_code_interface_outside_domain (default true). When false, the check silences every case where the caller isn't confirmed to be in the resource's domain: a different domain, a plain controller or LiveView, a domainless resource, or a :not_loadable resource (Opinion C).
• prefer_interface_scope (:auto | :resource | :domain, default :auto). Overrides which interface the check points at. :auto follows the in-domain/outside-domain heuristic; :resource always suggests a resource-level function (Opinion B); :domain always suggests a domain-level function.

Setting both enforce_* flags to false effectively disables the check for loadable resources. In this configuration prefer_interface_scope becomes inert, since no suggestion path fires, so combining Opinions A + B + C is observationally identical to A + C alone.

Contributing

1. Fork the repository
2. Create your feature branch (git switch -c my-new-check)
3. Apply formatting and make sure tests and lints pass (mix format, mix test, mix lint)
4. Commit your changes
5. Open a pull request. PR titles must follow the Conventional Commits format (e.g. feat: add check for XY, fix: handle XY edge case)

License

MIT, see LICENSE for details.