Soundcheck

Soundcheck is a Credo plugin for Phoenix LiveView. It finds bugs by checking how callbacks, HEEx templates, and JavaScript hooks work together: an event with no handler, an async task with no result callback, or an assign missing from the first render.

Some checks analyse source code directly. Others read compiled modules to resolve event handlers, components, routes, and mount hooks across files.

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

A set of high-confidence checks runs by default. All other checks are opt-in; the checks table lists which are enabled. When Soundcheck cannot resolve a dynamic value or external hook, it can report an unverifiable finding. These findings appear only when you enable Soundcheck's strict parameter or pass mix soundcheck --strict.

The name comes from the check musicians run before going live.

Installation

Supported versions: Elixir 1.18 or later, Phoenix 1.7 and 1.8, LiveView 1.1 and 1.2, and Credo 1.7.

With Igniter

If your project uses Igniter, run:

mix igniter.install soundcheck@0.1.0

The installer adds Soundcheck as a dependency with only: [:dev, :test], runtime: false, registers the plugin in .credo.exs, and adds a lint alias that compiles before running Credo. If you already have a lint alias, the installer leaves it as it is; make sure it runs compile before credo.

Manual

Add Soundcheck to your dependencies in mix.exs:

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

Fetch the dependency:

mix deps.get

Then add the plugin to your existing .credo.exs configuration:

%{
  configs: [
    %{
      name: "default",
      plugins: [{Soundcheck, []}]
    }
  ]
}

Running with Credo

Compile your project before running Credo:

mix compile
mix credo

For a repeatable workflow, add a Mix alias:

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

Then run mix lint. Credo's --strict option controls Credo's reporting; to include Soundcheck's unverifiable findings, set strict: true on the relevant checks in .credo.exs.

Checks marked semantic require a compiled project. They read handler clauses from module debug info, resolve on_mount hooks, and identify the components each template renders. If a module cannot be analysed, the Configuration check (SC000) reports the reason and the affected semantic checks stay silent. Checks marked syntactic work without compiling.

Checks

• Default: on checks run automatically; off checks must be enabled in Configuration.
• Tier: syntactic checks read source code; semantic checks also read compiled modules.
• Confidence: how certain the check is about the pattern it detects.

Use mix credo explain <file>:<line> for a check's full explanation and before/after examples.

Running with mix soundcheck

The standalone task compiles your project and runs the same checks, with text, JSON, or SARIF output. It shows every location involved in a finding, including exact locations in HEEx and JavaScript files. SARIF output includes related locations for code scanning.

mix soundcheck                      # default checks, plus .credo.exs overrides
mix soundcheck --all --strict       # every check, including unverifiable findings
mix soundcheck --only SC101,SC1002   # selected checks
mix soundcheck --format sarif --output soundcheck.sarif

Example output:

SC101 warning: `phx-click="add-trak"` has no matching `handle_event/3` clause in `MyAppWeb.AlbumLive`.
   --> lib/my_app_web/live/album_live.ex:127:30
    |
127 |     <.button phx-click="add-trak">Add track</.button>
    |                        ^^^^^^^^
   = help: Did you mean "add-track"?

The task reads check parameters, enabled and disabled checks, and the plugin's js_paths from .credo.exs. --all and --only override check selection while retaining configured parameters. It exits with status 1 if it reports any finding that is not unverifiable.

Command options

Configuration

Enabling and disabling checks

Add opt-in checks to checks.extra in .credo.exs. Use false to disable a check, or a keyword list to enable it with parameters:

%{
  configs: [
    %{
      name: "default",
      plugins: [{Soundcheck, []}],
      checks: %{
        extra: [
          # Enable an opt-in check
          {Soundcheck.Check.Design.UnusedEventHandler, []},

          # Customise an enabled check
          {Soundcheck.Check.Warning.UnhandledEvent, [ignore_events: [~r/^analytics-/]]},

          # Disable a default check
          {Soundcheck.Check.Warning.UndefinedHook, false}
        ]
      }
    }
  ]
}

To enable every opt-in check in Credo, use the following checks section. Default checks need no additional entries. For a standalone run, use mix soundcheck --all.

checks: %{
  extra: [
    {Soundcheck.Check.Design.ClickOnNonInteractiveElement, []},
    {Soundcheck.Check.Design.UnreadAssign, []},
    {Soundcheck.Check.Design.UnusedEventHandler, []},
    {Soundcheck.Check.Design.UnusedHook, []},
    {Soundcheck.Check.Readability.AssignsDotAccess, []},
    {Soundcheck.Check.Refactor.BareAssignsInTemplate, []},
    {Soundcheck.Check.Refactor.ChangeWithoutDebounce, []},
    {Soundcheck.Check.Refactor.ExpensiveCallInTemplate, []},
    {Soundcheck.Check.Refactor.ExpensiveMountWork, []},
    {Soundcheck.Check.Refactor.FormForChangeset, []},
    {Soundcheck.Check.Refactor.NavigateAcrossLiveSession, []},
    {Soundcheck.Check.Refactor.StreamCandidate, []},
    {Soundcheck.Check.Refactor.TemplateBoundVariable, []},
    {Soundcheck.Check.Refactor.TemporaryAssignCandidate, []},
    {Soundcheck.Check.Warning.BlockingCallInHandler, []},
    {Soundcheck.Check.Warning.CrashingMatchInCallback, []},
    {Soundcheck.Check.Warning.EventPayloadMismatch, []},
    {Soundcheck.Check.Warning.FormFieldMismatch, []},
    {Soundcheck.Check.Warning.FormWithoutRecovery, []},
    {Soundcheck.Check.Warning.LiveRouteWithoutAuthHook, []},
    {Soundcheck.Check.Warning.OptionalAttrWithoutDefault, []},
    {Soundcheck.Check.Warning.PossiblyUnsetAssign, []},
    {Soundcheck.Check.Warning.UndefinedStream, []},
    {Soundcheck.Check.Warning.UndefinedUpload, []},
    {Soundcheck.Check.Warning.UnhandledHookEvent, []},
    {Soundcheck.Check.Warning.UnhandledInfoMessage, []},
    {Soundcheck.Check.Warning.UnhandledServerPushEvent, []},
    {Soundcheck.Check.Warning.UnscopedLookupByClientParam, []}
  ]
}

JavaScript sources

The plugin scans assets/js for .js, .ts, and .mjs hook sources by default. Set js_paths to scan other directories:

plugins: [{Soundcheck, [js_paths: ["assets/js", "assets/vendor/hooks"]]}]

Shared check parameters

Every check accepts:

Check-specific parameters

Check names below omit the Soundcheck.Check.<Category>. prefix. Defaults containing ... are abbreviated; use mix credo explain <file>:<line> for the full check explanation.

For example, to include unverifiable event findings while ignoring analytics events:

{Soundcheck.Check.Warning.UnhandledEvent, [ignore_events: [~r/^analytics-/], strict: true]}

Suppressing findings

For an intentional exception, add a soundcheck:disable-* comment with a reason. Suppressions work in Elixir, HEEx, and JavaScript, with both mix credo and mix soundcheck.

# soundcheck:disable-next-line SC107 -- sent by a test helper

<%!-- soundcheck:disable-next-line SC101 -- pushed by an external widget --%>
<div phx-click="external-event"></div>

// soundcheck:disable-line UnusedHook -- mounted by the admin bundle

Selectors can be rule IDs (SC101), family wildcards (SC1xx), or check names (UnhandledEvent). Separate multiple selectors with commas or spaces. A suppression applies when it covers the finding's location or the line Credo reports it on.

SC001 reports missing or unknown selectors. With strict: true, it also reports suppression comments without a reason.

Adopting on an existing codebase

Use a baseline to record existing findings and report only new ones:

mix soundcheck --all --write-baseline

Commit the generated .soundcheck_baseline.exs. Both mix credo and mix soundcheck use it automatically.

Baseline fingerprints use the rule, file, and message, so moving a finding to another line does not make it new. Changing the finding itself does. Run the baseline command again after fixing findings to remove resolved entries. A run narrowed with --only or --path preserves entries outside its scope.

Use mix soundcheck --no-baseline to see all findings, or --baseline FILE to use a different baseline file.

How findings appear in Credo

Credo reports each finding at one location:

For JavaScript-only findings, use // soundcheck:disable-next-line to suppress them; Elixir # credo:disable comments cannot reach them. Each Credo issue carries the full finding in issue.meta[:soundcheck].

Use mix soundcheck when you need every related location or line-level JavaScript output.

Design

See docs/architecture.md for the architecture, planned rule catalog, and design decisions.

License

MIT. See LICENSE.