AshCredo

Unofficial static code analysis checks for the Ash Framework, built as a Credo plugin.

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

[!WARNING] This project is experimental and might break frequently.

Note: Only MissingChangeWrapper and MissingMacroDirective are enabled by default. All other checks are opt-in - enable them individually in your .credo.exs (see Configuration).

Installation

AshCredo requires Credo to already be installed in your project.

With Igniter (recommended)

If your project uses Igniter, a single command will add the dependency and register the plugin in your .credo.exs:

mix igniter.install ash_credo --only dev,test

This keeps ash_credo scoped to the same :dev/:test environments as credo. The installer also sets runtime: false.

Manual

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

def deps do
  [
    {:ash_credo, "~> 0.8", 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 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 (e.g. identities on AshAuthentication-injected :email attributes, fragment-spliced actions, extension-added authorizers).

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

Your project must be compiled before running mix credo, otherwise these checks emit a configuration diagnostic and become a no-op. Typically chain the two commands in a Mix alias:

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

If a referenced resource cannot be loaded, the check emits a per-call-site "could not load" issue pointing at the resource. If Ash itself is not available in the VM running Credo (why are you using ash_credo without depending on Ash?), 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.

Caching and long-lived VMs

Compiled checks cache introspection results (per-module facts, per-domain resource references, and the ash_available? probe) in Erlang's :persistent_term. This keeps a single mix credo run cheap - Credo dispatches each check × file pair into its own short-lived task, and :persistent_term is the only process-independent store that survives that task churn without the ETS ownership problem.

This has ramifications for setups that reuse a single BEAM across multiple Credo invocations:

• mix credo from the shell - each invocation boots a fresh VM, so the cache is always empty at the start. No action needed.
• Long-running iex -S mix sessions that invoke Credo repeatedly, file-watchers, custom Mix tasks that call Credo in-process - the cache persists across runs in the same VM. After you edit a resource and recompile, the code reload refreshes the modules themselves, but the cached introspection snapshots under the old module versions remain in :persistent_term until the VM exits. Compiled checks may then report on stale DSL state (missing an action you just added, flagging an identity you just introduced, etc.).

If you hit stale results in a long-lived VM, restart it or run AshCredo.Introspection.Compiled.clear_cache/0.

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 (Warning.MissingChangeWrapper and Warning.MissingMacroDirective are already on by default and do not need an entry):

checks: %{
  extra: [
    {AshCredo.Check.Warning.AuthorizeFalse, []},
    {AshCredo.Check.Warning.AuthorizerWithoutPolicies, []},
    {AshCredo.Check.Warning.EmptyDomain, []},
    {AshCredo.Check.Warning.MissingDomain, []},
    {AshCredo.Check.Warning.MissingPrimaryKey, []},
    {AshCredo.Check.Warning.NoActions, []},
    {AshCredo.Check.Warning.OverlyPermissivePolicy, []},
    {AshCredo.Check.Warning.PinnedTimeInExpression, []},
    {AshCredo.Check.Warning.SensitiveAttributeExposed, []},
    {AshCredo.Check.Warning.SensitiveFieldInAccept, []},
    {AshCredo.Check.Warning.UnknownAction, []},
    {AshCredo.Check.Warning.WildcardAcceptOnAction, []},
    {AshCredo.Check.Refactor.DirectiveInFunctionBody, []},
    {AshCredo.Check.Refactor.LargeResource, []},
    {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 three 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 - "in-domain caller → resource interface,
#            outside-domain caller → domain interface" hierarchy.
{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 (true default) - when false, leaves callers that share a domain with the resource alone (Opinion A).
• enforce_code_interface_outside_domain (true default) - when false, silences every case where the caller is not confirmed to be in the resource's domain (different domain, plain controller/LiveView, domainless resource, :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 - 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.