ala_lint: putting the ALA Checklist in CI

September 16, 2026 · ALA · ala_lint · tooling · Elixir

Every other post here leans on a tool called ala_lint. This one is about the tool itself: what it checks, how to run it, how to read what it says, and how it connects to the checklist notation from the thermometer post and the full checklist.

One framing up front, because it sets expectations. ala_lint is a gross filter, not a verdict. It rules out clearly-bad structure cheaply and in CI. It cannot tell you an abstraction is the right one, or that a design reads well. The full checklist is a human instrument; the linter is the part of it you can run on every commit. A green run is necessary, not sufficient.

Install

It will be on Hex shortly. Until then, and afterward if you like, add it as a dev-only dependency that never ships in your release:

# mix.exs
defp deps do
  [
    {:ala_lint, "~> 0.1", only: [:dev, :test], runtime: false}
    # or, from a checkout:  {:ala_lint, path: "../ala_lint_elixir", only: [:dev, :test], runtime: false}
  ]
end

It analyzes source by parsing, so it does not compile your project and needs none of your dependencies. You can also point it at a directory with no setup at all:

AlaLint.analyze("../some_project/lib") |> AlaLint.Report.to_text() |> IO.puts()

Run it

mix ala.lint                      # score lib/
mix ala.lint lib/app lib/app_web  # several roots; everything outside them is excluded
mix ala.lint --min-score 75       # exit non-zero below 75, the CI gate
mix ala.lint --help               # usage; unknown flags warn rather than being ignored

The options worth knowing:

Durable, per-check settings do not belong on the command line. They go in an optional .ala_lint.exs map at the project root, so the CLI stays small as the check list grows:

# .ala_lint.exs
%{
  layers_module: MyApp.AlaLayers,
  min_score: 85,
  checks: %{
    r7: :off,                       # off | advisory | scored
    height: [level: :scored, max: 4],
    public_surface: [max: 15]
  }
}

A check’s setting is a level (:off, :advisory, :scored) and an optional threshold, one uniform mechanism for turning a check off, changing its level, or retuning it. And there is a small honesty guard: a run that disabled or downgraded any check says so in its parameter echo, so a green score never quietly hides which rules it skipped.

Reading the output

A run prints a header, two headline scores, the findings, and the parameters it used. Trimmed:

── ALA Checklist (R1–R11) ──────────────────────────────────────────────
modules: 24   functions: 399   LOC: 6183
abstraction height: 9 call-levels (function graph)  ⚠ exceeds max 5
layer coverage: 303/399 functions assigned (76%)
  unassigned (worklist): App.Application, AppWeb.Telemetry, … +19 more

Degree of function compliance: 92/100  (grade A)
Count of compliant functions: 395 / 399  (99%)

Findings (scored, most severe first):
  [r1] lib/app/features/cart.ex:18  Cart.peek/1 [feature] → Wish.look/1 [feature]: cross-peer edge …

Advisory (reported, NOT scored — R7, height, pass-through):
  [passthrough] lib/app/x.ex:9  X.forward/1 is a pass-through (1 caller, 1 callee → …)

The two scores answer different questions, and you want both:

Grades are A ≥ 90, B ≥ 75, C ≥ 60, D ≥ 40, else F. Every finding carries a file:line, so a flag is one click from the code.

Two more lines in the header earn their place. Abstraction height is the longest chain of knowledge dependencies in the function call graph (calls within the application layer count as one altitude), and a deep stack is a proliferation signal worth a look. Layer coverage is the fraction of functions assigned to a layer, with the unassigned ones listed. On a codebase moving toward ALA, that worklist is the point: it tells you what is not yet organised.

The rules, and their honesty

The linter is explicit about which checks are exact and which are heuristic proxies for a human judgement:

R7, R11, module size, abstraction height, pass-through, tramp parameters, and a reference-level R1 signal are advisory: reported, never scored by default, because these are prompts for a reader (Spray never required reuse; a source-encoded app layer branches). --strict promotes the obtainable ones (R7, module-size, height, pass-through, tramp, R1-reference, self-subscription); --super-strict additionally scores the aspirational ones (R11 and public-surface); or promote any single check with --enforce. And R8 (does the composition read as the requirements?) is not checked at all; it is judgement, and it is where the tool stops and you begin.

LiveView checks (added 2026-10-01). Walking three variants to 100 by hand kept missing the same things, so the linter now looks for them. It reads HEEx as text: in an application template, a comparison, arithmetic, a case or if, a :for, or a call into a lower module is R11; in a lower layer’s markup, the words a person reads are R3, because the page should supply them. Below the page it also flags validation message: strings, sentences built by interpolation, and currency codes (R3), and a label like “Gift wrap ($2.99)” whose amount is also a configured number (R5). For features that declare ports/0, it checks the declaration against the outputs the code builds (:ports, promoted by --strict) and prompts for outputs no composer names (:ports_unwired). On the page it reports an assign passed into a feature’s or domain module’s input, and a private helper doing store work (R11), plus closures over page helpers in wiring (an R8 prompt). Three measures are reported and never scored: the share of application functions holding logic (because R11’s scale caps each kind of finding), message hops through a page that relays between LiveComponents, and the number of binding kinds a paradigm dispatches on. Two refinements cut false positives: a configured rule (call(%__MODULE__{unit: u}, n)) is no longer a “primitive wrapper”, and a configured instance is no longer a shared aggregate.

UI, sub-component and Features checks (added 2026-10-01 and 2026-10-02). ui_io (R6) flags a LiveComponent or component module below the composition that loads or saves: it calls a module reaching the Repo or PubSub, a configured I/O instance, or a module held in a variable or assigns. Spray wires data sources to the UI element that shows the data (§5.2.2). subcomponent (R11) flags a LiveComponent in the application or a Features layer. A page-specific component with its own state and handlers is a sub-component, and Spray has “no analog of a sub-module or sub-component” (§2.2). Both are scored by --strict. A layer named :feature, :features, :user_story(ies) or :story(ies), or marked composition: true, is now a composition layer, because Spray’s features hold “instances of domain abstractions” that a feature “configures” and “connects” (§2.2). It gets R11’s checks, may hold application literals, and isn’t checked as a lower layer. A layer of coded state abstractions should be named for what it holds, or keep its name with composition: false. With a layer map, a module that matches no layer raises a loud unassigned warning, because the layer-aware checks skip it.

Rules met, not just a score (added 2026-10-02). The score is a density: weighted findings per 100 functions. In a codebase of about 5,000 lines one finding rounds away, and that finding can be the one that matters. So the report now opens with a count: “Checklist rules met: 9 of 10 checked”. A rule is met when none of its checks has a scored finding at the current tier, and a second count includes advisory findings. R8 is judgement and never checked, and R11 needs a layer map. The max variants and V45 all score 100 under --strict, but they meet 9 of 10, because their generated FormComponent leaves R11 unmet. V46 and V47 meet all ten.

Refinements from building V46 and V47. Each of these was a finding the checklist’s own rules say isn’t one:

It also fixes a crash when a module declared ports and nothing composed it.

Refinements from building V51 (added 2026-10-03). Two more findings the checklist’s rules say aren’t findings:

Re-linting V46 to V50 after both left every score and rules-met count the same.

Names shared across modules (added 2026-10-03). The first version of V51 linted at 100 with R5 met, though the hand walk found three silent contracts in it. A story’s template fired event names the page’s handle_event matched, and a story started a timer and a task whose names the page’s handle_info and handle_async matched. The R5 check compared only string literals in code. It didn’t read template markup or function heads, and it skipped atoms. R5 now also pairs an event a template fires (phx-click="...", or event="..." and on_*="..." handed to a component) with a handle_event head in another module, and a literal name given to start_timer or start_async with a handle_info or handle_async head in another module. Three cases aren’t flagged:

On a copy of V51 with the three contracts put back, it reports all of them. Across the published variants, it changes only two archived ones. V30 and V35 each have a generic effect interpreter that starts a task named :checkout for the page to match, and V30 also has a feature component firing an event the page handles. Each is a real contract, and both variants already missed R5.

Assigning layers

The layer-aware checks (R1 altitude, coverage) need to know which tier each function sits in. You declare that; the tool does not infer it, because inferring layers from the call graph would make “does this edge drop?” trivially true. A layer is matched by a function’s own @ala_layer tag, or by what it uses (a schema is persistence even in a domain namespace), or by module-name pattern or filesystem path:

def layers do
  [
    {:app,       [~r/Web\..*Live$/],        paths: [~r{/live/}]},
    {:feature,   [],                         paths: [~r{/features/}]},   # a composition layer (§2.2)
    {:domain,    [~r/App\.(Cart|Pricing)$/, ~r/Web\.Components\./]},
    {:paradigms, [~r/Interpreter$/, ~r/Effects/], uses: [~r/Ecto\.Schema/, ~r/Ash\.Resource/]}
  ]
end

Peers are forbidden below the top layer unless a layer declares peer_ok: true. Only page-specific code goes in the application: generic components are domain (UI) abstractions, and a generic effect interpreter is an execution model in the paradigms layer, as the checklist’s LiveView section explains.

With no layer map the tool skips coverage and R1-altitude and runs the structural checks that need no layers. That is the on-ramp for a codebase not yet layered.

Tightening the gate: a strict run

Default mode scores the structural rules and leaves the advisory ones as a reading list. The two tighter modes turn those into gates, and it is worth seeing all three side by side across the LiveView variants. Re-scored 2026-10-01 with the current linter and layer maps that now place every module: the product pages, plugs and controllers in the application layer, SaveProduct in the domain, and the paradigms in the bottom layer (V42 also with its diagram modules in the application layer). The earlier maps left those modules unassigned, and the linter now warns loudly when a map does that, because the layer-aware checks skip unassigned code. The LiveView checks added that day account for most of the movement since the 2026-09-30 table: R11 now reads templates, so a comparison, a :for or a case in a page’s markup counts, and R3 now counts validation messages, interpolated sentences and currency codes below the page. Strict scores fell by one to four points and super-strict scores by up to fourteen. V38 was also built out to the full requirements the same day, with its logic kept in its LiveViews by charter, which is why its super-strict score fell to 51:

target                  normal   --strict  --super-strict
v30 committed-codegen    86/B     85/B       75/B
v33 flows+purity         87/B     86/B       71/C
v34 manifest-config      91/A     90/A       75/B
v35 composed-inputs      91/A     90/A       77/B
v36 vernacular-core      87/B     87/B       81/B
v38 lint-guided          96/A     95/A       51/D   (built out to the full requirements)
v39 bound-ports          95/A     94/A       82/B
v40 circuit-instances    96/A     95/A       84/B
v41 feature-components   95/A     94/A       89/B
v42 typed-circuit        95/A     95/A       87/B
v38-max                 100/A    100/A       99/A
v39-max                 100/A    100/A       99/A
v41-max                 100/A    100/A       99/A
v45 checked-clauses     100/A    100/A       99/A

--strict scores the obtainable advisories: pass-through helpers, unearned abstractions (R7), oversized modules, deep stacks. The codegen and flows variants carry a handful of one-in/one-out forwarding functions that strict counts. V36 has no pass-throughs and no oversized modules, so --strict changes nothing for it. Its default score fell from 94 to 87 when R3 started counting message text: the five flash strings its features hold (“Added to wishlist”, “Your cart is empty”) are application literals the revised checklist says belong at the page.

--super-strict adds the aspirational-purity checks: R11 (no logic at the top) and a public-surface check. Everything drops here, V36 included (87 → 81), mostly from R11: branches, arithmetic, loops, and handling data in the page. Those findings are real. Spray’s application has “no … assignments and if statements”, and the checklist’s R11 sorts each branch into a kind with a way to move it. R11 lives in super-strict rather than strict because a LiveView page gets to zero only by adopting a design built for it (a binding map, a circuit, instances that announce, or clauses as wires), and that’s a team’s choice, not a gate’s. Routing clauses, with, and the connected? guard aren’t counted, so what’s left is logic you can move. Super-strict is where you work the remaining findings down; strict is the CI-worthy gate.

What the public-surface check counts, since a module is not an ALA concept: an abstraction’s input ports, which in Elixir are its public functions. A state module with twelve public functions is one abstraction with twelve inputs, not twelve abstractions, and a one-function module would be a port per module. The count is a proxy for R7’s “one concept”: the default of 12 sits just above the largest single-concept modules in the variants (the step machines and the lines value at 11 and 12), with nothing at 13 and the two modules above it, at 14 and 19, the two later split on other grounds. One app’s distribution, so it is advisory and --set public_surface.max retunes it.

An accuracy note underneath all of it: these counts exclude false positives a naive call-graph would report. HEEx function components (defp tabs(assigns) rendered <.tabs/>) live inside a ~H string the AST never sees; &capture/1 references and quote-injected defs have call sites the graph misses; ~p"/route" strings are compile-checked, not silent contracts; and a call piped into another call is a transform, not a rename. ala_lint accounts for each, so the numbers above reflect design, not tooling artifacts.

The light-ALA preset (2026-10-29)

Light ALA keeps the layers, calibration at the top and named rules, and drops ports, wiring and pages that only compose. Scored by the full checklist, a light-ALA app would fail R9 to R11 on purpose. One switch scores it as what it is:

mix ala.lint --preset light_ala --strict

or preset: :light_ala in .ala_lint.exs (and in AlaLint.analyze/2’s options).

The preset is a whitelist of the checks light ALA adopts: R1 to R7 and the general checks (layer validity, subscribe, tramp, ui_io, module size and averages, pass-throughs, height, public surface, clone, clone_inside, unassigned modules), plus the two light-ALA checks below when they are configured. Everything else is off, including R9, R10, R11, r11_share, app_share and the port and wiring checks. A whitelist rather than a list of checks to turn off, so that a check added to the linter later stays off under the preset until someone decides it belongs to the reading, instead of silently scoring light-ALA projects. Explicit checks: settings override it: tier default, then the preset, then the file’s level, then --enforce, then --disable.

Not adopted. A checklist rule whose checks are all off used to report as met, which made a switched-off rule look passed. It now reports as not adopted and is left out of both counts. V59 under the preset, at --strict:

Checklist rules met: 7 of 7 checked (11 in the checklist; R8 is judgement)
  not adopted (their checks are off): R9, R10, R11; left out of both counts
  R1 met  R2 met  R3 met  R4 met  R5 met  R6 met  R7 met (1 advisory)  R8 unchecked  R9 not adopted  R10 not adopted  R11 not adopted

Degree of function compliance: 100/100  (grade A)

This applies under any configuration, not only the preset, so V54 to V59, whose lint.exs turns those checks off, now report 7 of 7 rather than 10 of 10.

Two checks for light ALA’s own rules. Two of V59’s twelve rules came from failures the change runs found, and each has a check. They are readings for light ALA, not checklist rules, so they count toward no R-number; they are off until configured, advisory once configured, and scored under --strict or the preset.

# .ala_lint.exs
%{
  preset: :light_ala,
  checks: %{
    # rule 11: config and context structs are built only by their builders, which take keyword overrides
    builder_literals: [structs: ["MyApp.Channel", "MyApp.Shop"], tests: ["test"]],
    # rule 12: a LiveView event that writes a session-scoped resource needs the guard in mount
    stale_session_write: [writers: ["MyApp.ShoppingCart"], except: [~r/^(get_|list_)/],
                          guards: ["MyAppWeb.CartSession.guard_open_cart"]]
  }
}

Encoding your code into the checklist notation

The thermometer post introduced a small notation for writing an ALA design down: f [tag] functions, pN wires, $ hidden state, qN silent contracts, an optional @name-Lidx level, and {app-literal?}/{app-literal}/{intrinsic-literal} marks for configuration literals. ala_lint can produce a first draft of that encoding for a whole codebase.

mix ala.encode                    # write a parallel .ala.md tree of lib/ to ala_encoding/
mix ala.encode --layers-module MyApp.AlaLayers   # with the @levels filled in
mix ala.lint.encoding             # check a completed encoding tree

mix ala.encode walks your code and writes one .ala.md file per source file, mirroring the tree. It fills what a machine can: the fully-qualified function names, the dependency edges annotated with whether each drops, the @name-Lidx levels from your layer map, and a {app-literal?} seed on every function that owns a configuration-candidate literal (the value stays opaque; the linter has its file:line). It leaves the things only a human can judge: the semantic [?] tag (what does this code know?), and whether each {app-literal?} is really top-level {app-literal} or {intrinsic-literal} to the implementation.

It also stamps the facts a linter can decide, so the encoding does not fall behind the checks that live in the tool’s call-graph analysis: &entity/&aggregate where a module shares a domain entity with peers (R10), ~> on a pass-through, (branches) on an application-layer function that branches (R11), and (private) on private functions (so public-surface and pass-through scoping stay honest). You keep those marks as written; you only fill in the tags and resolve the literals.

That draft is the intermediate checklist data. A human completes it, and mix ala.lint.encoding then checks the completed tree: edges that do not drop, $ and q marks to confirm, {app-literal} literals still sitting below the composition, the stamped R10/R11/pass-through/public-surface marks, and anything left unresolved. The goal is that a correctly completed encoding re-lints to the same findings the linter reports on your source — R6 and R7 aside (pure judgement, never encodable), and the tramp-parameter check (the encoding doesn’t carry parameters), plus abstraction height and the R11 app-share aggregate, which the encoding can only approximate because it carries module-level edges rather than the full call graph. It is the bridge between the mechanical scan and the full checklist, and it is where the tool hands the judgement calls back to you with the structure already filled in.

Where it fits

Adopt it one strictness level at a time, because the three flags are a gradual-adoption path, not just settings. Start with the default mix ala.lint --min-score N in CI and a declared layer map so R1 and coverage light up — the Required tier, the structural floor. When that is quiet, turn on --strict and treat its Advisory signals as a reading list, promoting individual checks with --enforce (or a .ala_lint.exs file) as the team agrees they are worth a gate. Reach for --super-strict and its Aspirational purity checks last, on greenfield or mature code, reading each flag as a question rather than a defect. The checklist post walks that same tier-by-tier path across the rules and the encoding together. Use the encoding when you want to walk a design against the checklist by hand with the mechanical parts already done. And remember the framing: the linter clears the floor cheaply so that human attention goes to the things it cannot see, which is most of what makes a design good.

← all posts