ala_lint: putting the ALA Checklist in CI
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:
--min-score Nfails the build below a threshold. This is the line you put in CI.--layers-module MyApp.AlaLayersturns on the layer-aware checks (see below). You can also set it once in.ala_lint.exsand drop the flag.--list-checksprints every check, its tier (required / advisory / aspirational), and the threshold flag that tunes it. Run it once and you never have to memorise the surface.--enforce CHECKpromotes one advisory check to scored;--disable CHECKturns one off;--set KEY=VALUEretunes a threshold (height.max,module_size.max,public_surface.max,app_share.max,min_score). These are the per-check knobs, generic so the CLI does not grow a flag per check.--config-module Fooexempts a config or manifest module from the R3 check when you have no layer map.--limit Nshows more findings.--strictpromotes the obtainable advisory checks (R7, module-size, height, pass-through, tramp parameters, the reference-level R1) into the score, so genuine cruft can fail the build.--super-strictgoes further, scoring the aspirational-purity checks: R11 (no logic at the top) and a public-surface check (keep the little ball of mud encapsulated). R11 sits in super-strict rather than strict because reaching zero in a LiveView app takes a particular design (V39, V40 and V41 get there by different routes), and a CI gate shouldn’t choose the design for you. Three checks are reported at every tier and scored by none, because they are ratios or design choices rather than defects: the app-layer share of functions, files averaging under 100 lines, and the shared-domain-aggregate reading of R10;--enforcescores one if you want it. Phoenix’s generated framework files (core_components.ex,telemetry.ex,endpoint.ex, …) are skipped unless you ask for them. Pair either with--min-scoreto gate CI at the strictness your team wants. Default keeps the advisory checks as a reading list.
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:
- Degree of function compliance is
100minus the weighted violation load. It counts findings, severity-weighted, so a few dense or data-heavy modules can drag it down. It is the sensitive number. - Count of compliant functions is the share of functions with zero violations. Each function counts once, so it cannot be inflated by one messy module, which makes it stable and comparable across codebases of different sizes.
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:
- R1 (edges between abstractions drop), with a layer map, flags upward calls and calls between two different abstractions in the same layer. Every layer below the application forbids peers unless you say otherwise, so domain → domain counts too. Without a layer map it falls back to module dependency cycles. Exact. An advisory companion flags a module that subscribes itself to a topic it fixes, a receiver choosing its own sender (Spray §4.4.2).
- R2 (shared mutable state) flags
:ets/Agent/process-global use. R4 (hidden state) flags the process dictionary. Exact. R5 (silent contracts) flags identifier strings duplicated across modules. Exact. - R9 (no owned interfaces) flags a
@callbackor protocol that a peer, or a lower layer, implements. A port interface belongs below its implementers. Exact on explicit@behaviour/defimpl. The rest of R9, whether outputs announce rather than command and whether a struct is a peer’s DTO, is left to a reader. - R3 (application literals) flags numeric literals below the composition layer, including numbers in guards, and multi-word message text (a flash, a label) in a declared lower layer: text a person reads is the page’s business. R6 (nameability) and R7 (unearned abstraction) are heuristics, tuned to be quiet.
- Tramp parameters (R6’s “should”) is an advisory heuristic. It flags a public function that never reads a parameter and only carries it into another module’s function, which doesn’t read it either and passes it further down. That’s Spray’s complaint that middle-layer functions “end up with extra parameters that don’t have anything to do with them, just so they can pass state data through to even lower functions” (§3.11.1). It needs two hops because one hop is ordinary: a function handing its own input to the abstraction that processes it is using that abstraction. It skips private helpers, framework callbacks, pass-throughs, the application layer (R11 already covers data handling there), and anything carried into a protocol or behaviour, which is a runner delivering to a port.
- R10 (no shared entity) flags a struct read by two units of its own layer, such as two features sharing a feature’s struct. That’s what a shared identity key plus private data avoids. Scored. Its stricter cousin, R10-aggregate, flags a struct in a lower layer that two features read. Is it a legitimate domain abstraction or a shared entity? Only a human can say, so it is reported under
--strictand above and scored by no tier. - R11 (the top layer is composition only) reports when a top-layer function branches, when it does arithmetic, when it iterates (a
forcomprehension, Spray’s “for loop” at §1.6.3), when it handles data (binds a lower-layer call’s result and passes it to another lower-layer call, or passes one straight into another’s call as an argument, the shape Spray moves past in §1.6.3; a nestednewthat builds an instance’s configuration isn’t counted, and neither is a pipe of stages, since that’s how Elixir writes his §1.6.4 chain), or when it is part of a working chain (an app function calling another app function that computes or decides). Branches are labelled guard or logic.with, acasethat only routes ok/error outcomes, and LiveView’sconnected?/1guard aren’t counted: they’re the connection mechanism, routing, and the one framework departure the checklist names. The application layer’s share of all functions is reported separately and never scored. The findings are real. A LiveView page can reach zero, but only with a design built for it (V39, V40, and V41 each get there differently), so R11 is reported by default and scored only under--super-strict.
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:
- Naming a built instance so it can be wired twice (
rule = Rule.new(2)) isn’t handled data (Spray §1.6.6). - A function capture handed to a runner (
&Products.get!/1) isn’t a call made in a page helper. - A function that computes an argument before it delegates is an adapter, not a pass-through.
- A story’s outputs are its
send_out*calls and{:out, port}bindings, not its configuration lists. - A struct in the bottom layer, like a runner’s state or a schema, isn’t a shared domain aggregate.
- A paradigm’s own interpolated text, like a checker’s messages or a diagram’s labels, isn’t product words.
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:
- A story can send an output by calling the function it was given for its outputs,
out.(socket, {port, payload}). That call is now a sent output, alongsidesend_out*calls and{:out, port}bindings. Without it, V51’s eight stories got 26 “declares output but never emits it” findings. - A page binding a key to its own
wire/3(&wire(&1, key, &2)) isn’t an opaque closure. It names where a story’s outputs go, and the page’swire/3clauses for that key say what happens to them. Any other capture of a private page helper is still reported.
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:
- a name the naming module also handles itself;
- a name both ends take from the composition’s configuration;
- a page’s view module and the page, which together are the application, Spray’s symbolic connection kept inside one abstraction.
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"]]
}
}
builder_literalsflags a literal of a guarded struct (%Shop{},struct!/2) outside its builder, inliband in the test paths you give it, and a builder that takes optional fields positionally rather than as a keyword list. It infers the builders (the modules that return the struct) unless you name them. On the hybrid-1 code it flagsCartSession.shop/3, the positional builder whose new parameter broke 119 tests through one shared fixture.stale_session_writeflags a LiveView whose events call a configured writer while itsmountattaches none of the configured guards, listing the events. On the hybrid-1 code at its reorder change it flagsOrderLive.Show’s"reorder", the event that wrote reordered lines into a cart that had already been ordered. It does not trace where the id came from, so a page whose events re-read the session will be flagged too; name such a function inexcept:. A controller action is not flagged: it runs through the session plugs.
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.