ALA Lint (ala_lint_elixir)

A static-analysis linter that scores an Elixir codebase against the ALA Checklist (R1–R11): coupling & layering, requirements-locus, state-as-a-wire, cross-boundary contracts, nameability, and abstraction minimality. It walks lib/**/*.ex, reports each violation with a location, and computes an overall design-health score.

New to ALA? getdown.dev has an introduction to it, guides to applying it, and worked examples, including posts on this linter and the checklist.

This is the Elixir implementation of the ALA Checklist and encoding. The checklist itself is language-agnostic and lives in its own repository: modellurgist/ala_checklist. Example designs the linter is applied to live in modellurgist/ala_variants_elixir.

It analyzes source by parsing (Code.string_to_quoted); it does not compile your project, so it runs on any codebase without its deps.

An independent, unofficial implementation based on John Spray's Abstraction Layered Architecture. Not affiliated with or endorsed by the author.

Install

# mix.exs
defp deps do
  [
    {:ala_lint, "~> 0.1", only: [:dev, :test], runtime: false}
  ]
end

mix ala.lint                      # score lib/
mix ala.lint lib/my_app           # a subtree
mix ala.lint lib/app lib/app_web  # several roots — everything outside them is excluded
mix ala.lint --limit 100          # show more findings
mix ala.lint --layers-module MyApp.AlaLayers   # layer-aware R1/R3 + coverage
mix ala.lint --min-score 75       # exit 1 if below 75 (CI gate)
mix ala.lint --strict             # score the obtainable advisory checks too
mix ala.lint --list-checks        # every check, its tier, and its threshold
mix ala.lint --enforce r7         # promote one advisory check to scored
mix ala.lint --disable r3         # turn one check off (and say so in the output)
mix ala.lint --set height.max=4   # retune a threshold (height/module_size/public_surface/app_share/min_score)
mix ala.lint --help               # usage; unknown flags warn instead of being ignored

mix ala.encode                    # write an ALA-notation draft of lib/ to ala_encoding/
mix ala.encode --layers-module MyApp.AlaLayers   # with [tag]s filled in
mix ala.lint.encoding             # lint a completed encoding tree (R1/R3/R4/R5/R10/R11 + advisories)

Every task also has a real --help, and mix help ala.lint prints the full task docs. Unrecognised options warn (ignoring unknown option(s): …) rather than being silently dropped.

On "config" here. A config module (--config-module) or a config layer (config: true in a layer spec) names a place where application literals — the product-specific constants R3 wants at the composition — are allowed to live. It is not about the value's nature (that is the application-literal / intrinsic-literal distinction); it marks the composition, or a manifest standing in for it. --config-module is the fallback for a codebase with no layer map and is ignored once one is given; with a layer map, R3 uses the config: true layer (defaulting to the top).

Accepting a finding by hand (ala:accept, @inherent_)

Several checks turn on a judgement the tool can't make: whether a word below the composition is the product's (hoist it) or the abstraction's domain's own (keep it; the checklist's R3 exception), whether a page's branch is routing or logic, whether a shared struct is a ground symbol. A comment on the line above records the reviewer's call where the code is, names the exact check, and takes that line (or the next N lines) out of the score for that check only:

# ala:accept r3 -- "Out of stock" is retail's word, not this store's (R3, domain vocabulary)
def label, do: "Out of stock"

# ala:accept r3,r6 lines=2 -- two checks, the next two lines

<%!-- ala:accept r11 -- the one loop this page keeps, until a rows component exists --%>
<div :for={row <- @rows}>…</div>

For words there is a declaration instead of a comment: a module attribute named @inherent_... holds the abstraction's own vocabulary, and R3 reads nothing inside it as product text.

The check names are the ones --list-checks prints; an unknown one fails the run. Accepted findings leave the score and the rules-met count, and the report says how many were accepted and under how many comments. mix ala.lint --list-accepted prints every @inherent_ declaration and every comment with the findings it covers, and marks the ones that cover nothing, which is how a stale acceptance shows up after the code moved.

Configuring checks (.ala_lint.exs)

The CLI carries the common path (paths, tiers, --min-score). Durable, per-check settings live in an optional .ala_lint.exs map at the project root, so the command line stays small as the check list grows:

# .ala_lint.exs
%{
  layers_module: MyApp.AlaLayers,
  min_score: 85,
  config_modules: ["MyApp.Manifest"],
  exclude: [~r{/components/}],
  checks: %{
    r7: :off,                    # off | advisory | scored
    r3: :advisory,               # downgrade a scored (required) rule to reported
    height: [level: :scored, max: 4],
    public_surface: [max: 15],
    module_size: [max: 400]
  }
}

A check's setting is a level (:off | :advisory | :scored) and/or a threshold (max:). One mechanism covers "turn it off", "change its level", and "retune it", for any current or future check. mix ala.lint --list-checks prints every check, its tier, and its threshold flag.

For a single run the generic flags override the file: --enforce CHECK promotes one advisory check, --disable CHECK turns one off, --set KEY=VALUE retunes a threshold (height.max, module_size.max, public_surface.max, app_share.max, min_score). 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.

A layers module is any module exporting layers/0 that returns a layer spec (see AlaLint.Layers). Declare it once with config :ala_lint, layers_module: MyApp.AlaLayers and both ala.lint and ala.encode pick it up with no flag. ala.encode writes a parallel .ala.md tree a human completes; ala.lint.encoding then checks that tree. It scores what the notation carries: R1 edge altitude, R4 $, R5 q, R3 via {app-literal?}/{app-literal}/{intrinsic-literal} literal marks, and — from marks the encoder stamps rather than asks a human to judge — R10 (&entity/ &aggregate), R11 ((branches) on an app-layer function), pass-throughs (~>), and public surface (via (private)). R6/R7 stay unencodable, and so does the tramp-parameter check (the encoding doesn't carry parameters); height and the R11 app-share aggregate are reproduced only approximately (the encoding carries module-level edges, not the full call graph). The encoder seeds {app-literal?} on each function owning a configuration-candidate literal (value opaque; the source scan has its file:line); a reviewer resolves it to {app-literal} (an application literal — hoist if it isn't at the top) or {intrinsic-literal} (intrinsic to the abstraction, kept local). The aim is that a correctly completed encoding re-lints to the same findings the source lint gives.

Assigning functions to layers

Each layer declares matchers; a function is assigned most-specific-wins: its own @ala_layer :name attribute > a uses: content match (the module's use macros — e.g. a schema is persistence even in a domain namespace) > the first layer whose module-name pattern or filesystem paths: glob matches > unassigned. Layers are a design decision you declare, never something inferred from the call graph (inferring them would make R1 tautological). You can also pass multiple include roots to restrict analysis to your real code (AlaLint.analyze(["lib/app", "lib/app_web"])), excluding boilerplate elsewhere.

def layers do
  [
    {:app,       [~r/Web\..*Live$/],           paths: [~r{/live/}]},
    {:feature,   [],                            paths: [~r{/features/}], unit: ~r/(App\.\w+)/},
    {:domain,    [~r/App\.(Cart|Pricing)$/, ~r/Web\.Components\./]},
    {:paradigms, [~r/Interpreter$/, ~r/Effects/, ~r/Foundation/]}
  ]
end

Peers are forbidden in every layer below the top unless it declares peer_ok: true (checklist R1: domain → domain is a peer edge too); the top layer allows them, because the application is one abstraction. Following the checklist's model of a LiveView app, only page-specific code is application: generic components are domain (UI) abstractions, and a generic shell or effect interpreter is an execution model in the paradigms layer. (app: true on several layers, to model shell → page → view sub-layers, still works but is the older model.)

A Features layer is a composition layer. Spray's features hold wiring, like the application: "Each feature creates instances of domain abstractions, configures the instances with feature specific details, and connects them together as needed to express the feature or user story" (§2.2). So a layer named :feature, :features, :user_story, :user_stories, :story or :stories, or any layer with composition: true, gets the application's R11 checks, may hold application literals (R3), and isn't checked as a lower layer. A layer of coded state abstractions (a cart with its rules, an undo offer) is a domain layer in Spray's terms. Name it that way ({:state, ...} above {:domain, ...}), or keep the name with composition: false.

A feature's parts must read as one unit. With unit: ~r/^(App\.Features\.[^.]+)/, a feature's UI instance named App.Features.CartPanel counts as a peer of App.Features.Cart (R1 and R10 findings); named App.Features.Cart.Panel, it is the same unit. Name a feature's parts under the feature, or widen the unit regex.

The report then gives three things a migration cares about: layer coverage (% of functions assigned, with the unassigned worklist), validity errors (a @ala_layer tag naming an undeclared layer), and R1 (do the assigned function→function edges drop?). With no layer map, coverage is skipped and the structural checks that need no layers still run — the on-ramp for a codebase not yet organised into layers.

Or as a library, without adding a dep to the target (point it at any path):

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

The rules (and their precision — this matters)

The checklist mixes exact structural facts with heuristic proxies for judgement calls. AlaLint is honest about which is which:

Rules met. The score is a density (weighted findings per 100 functions), so a few findings in a large codebase round away even when they matter. The report also counts the checklist rules met: 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 is never checked; R11 needs a layer map. Each check counts toward one rule (ui_io and tramp toward R6, subcomponent toward R11, ports toward R9, the size and depth checks toward R7). The report map carries it as rules: %{met: 9, checked: 10, total: 11, met_strictly: 7, by_rule: %{r11: %{state: :not_met, scored: 1, advisory: 0}, ...}}.

Strictness modes

• default — the required checks are scored (see below); everything else is advisory (reported).
• --strict — promotes the obtainable advisory checks (R7, module-size, height, pass-through, tramp, R1-reference, subscribe, declared-port drift) to scored, so genuine cruft can fail the build.
• --super-strict — --strict, and additionally scores the aspirational-purity checks: R11 (no logic at the top) and public-surface (keep the little ball of mud encapsulated behind a small API). These are impractical to zero out in a real app and contested as metrics, so they are super-strict gates, not strict ones, while still being reported by default.
• Reported at every tier, scored by none: app_share, module_avg and R10-aggregate. Each is a ratio or a design choice rather than a defect; --enforce CHECK scores one.

Phoenix's generated framework files (core_components.ex, layouts.ex, telemetry.ex, gettext.ex, endpoint.ex, error_html.ex, error_json.ex, application.ex, mailer.ex, repo.ex) are skipped by default; pass include_framework: true to AlaLint.analyze/2 to score them.

Pair any mode with --min-score N to gate CI at the strictness you want. The required (scored by default) checks are R1, R2, R3, R4, R5, R6, R9, R10, and layer-validity; the advisory ones are R7, module-size, abstraction-height, pass-through, tramp, R1-reference, subscribe (promoted by --strict), plus R11 and public-surface (promoted only by --super-strict); app_share, module_avg and R10-aggregate are reported and never promoted by a tier. R9 is checked for owned interfaces (scored); its other parts are judgement. R8 is not checked (judgement).

R7, R11, module-size, abstraction height, pass-through, tramp, and the reference-level R1 signal are advisory — reported but not folded into the score. Reuse is evidence not a requirement (Spray never demanded a second caller), and a source-encoded app layer legitimately branches, so the tool won't fail a build on these alone. Promote any to a hard failure with --enforce r7 / --enforce r11 / --enforce height / etc. R9 (ports typed by a paradigm; no abstraction owns an interface except its own configuration) is checked for owned interfaces; whether outputs announce rather than command, and whether a struct on a port is a peer's DTO, are left to a reader. R8 (reads as the requirements) is not checked — it is judgement. Every run echoes its effective parameters (max_height, max_app_share, max_module_loc, enforce set, layers on/off, weights, config/exclude) so results are reproducible and you know exactly what was and wasn't checked.

R1 altitude, height, and pass-through all run on a function→function call graph (each Module.fun/arity a node, remote calls resolved through the module's alias table). Only R1's no-layer-map fallback (cycle detection) stays at module granularity — a function-level cycle is usually legitimate recursion, whereas a module cycle is the real coupling smell.

R8 (readability) — names, config clarity, "the composition reads as the spec" — is not checked. It is judgement; a high score is necessary but not sufficient. See the ALA Checklist.

Two design choices worth knowing:

• Generated files are skipped (any file whose head contains GENERATED). Derived code legitimately duplicates its source — e.g. committed codegen kept in sync by a --check — and must not be scored as hand-authored design. Without this, a manifest→generated pair looks like massive R5 duplication when it's actually the safest arrangement.
• ~H markup is opaque to the AST, so contracts inside HEEx templates (phx-click="…") are not seen — AlaLint checks Elixir-level structure. (Markup-level contract checking is what a ContractPurity-style Credo check does; the two are complementary.)

The score

Each rule carries a severity weight (coupling core R1/R2/R5 = 3; state R4 = 2; design smells R3/R6/R7 = 1). The headline density is weighted violations per 100 functions — functions, not lines, because the checklist is about how abstractions relate:

W        = Σ weight(rule) × count(rule)
density  = W / functions × 100          # weighted violations per 100 functions (headline)
per_kloc = W / loc × 1000               # weighted violations per 1000 LOC (secondary)
score    = clamp(100 − density, 0, 100) # 0–100, higher is better

Grades: A ≥ 90, B ≥ 75, C ≥ 60, D ≥ 40, else F.

Is a function counted more than once? In the severity score, yes — its numerator counts findings, so a function with several problems weighs several times, and a data-heavy module can exceed 100 findings/function (e.g. a colour-table library scored 3369/100fn). That is why there is a second, bounded metric:

Count of compliant functions (the bounded metric)

offending  = distinct functions with ≥1 finding
compliant  = functions − offending         # functions with ZERO violations (a raw count)
compliant% = clamp(100 − offending/functions×100, 0, 100)   # 0–100, higher = cleaner

This counts each function clause at most once, so it can't be inflated by one function accruing many findings. Both metrics use clauses (a five-clause handle_event/3 is five), the unit findings attach to; the header also gives the distinct count, one per module, name and arity, which is the better number for comparing how finely two codebases are factored: functions: 277 (392 clauses). Findings that belong to no function — R1 cycles, R5 duplicated literals, and magic literals in module attributes — are module-level and reported separately (not folded in).

The two metrics answer different questions and are both reported (both: higher = cleaner):

• Degree of function compliance (was "severity") — 100 − weighted violation load. Counts findings, severity-weighted, so a few dense or data-heavy modules can drag it. Its input, the violation load per 100 functions, can exceed 100 (multi-counts) — that's the "high = bad" number.
• Count of compliant functions (was "breadth") — how much of the code is clean; bounded, stable, comparable across sizes.

In a study of popular Hex packages the compliant-function % was far tighter (mean ≈92, σ ≈6) than the degree-of-compliance score (mean ≈64, σ ≈30), precisely because it doesn't multi-count.

Example output

An illustrative, abridged report for a small app:

── ALA Checklist (R1–R11) ─────────────────────────────────────────────
modules: 24   functions: 312 (399 clauses)   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
filesystem cohesion (advisory — Spray: dirs separate layers):
  feature    100% under `lib/app/features` (cohesive)
  domain      81% under `lib/app/domain` (scattered across 2 dirs)

Checklist rules met: 9 of 10 checked (11 in the checklist; R8 is judgement)
  with no finding at all, advisory included: 8 of 10
  R1 NOT met (1)  R2 met  R3 met  R4 met  R5 met  R6 met  R7 met (1 advisory)  R8 unchecked  R9 met  R10 met  R11 met

Degree of function compliance: 92/100  (grade A)
  weighted violations: 30   violation load per 100 functions: 7.5
Count of compliant function clauses: 395 / 399  (99% → grade A)

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 reuse/minimality, abstraction height):
  [passthrough] lib/app/x.ex:9  X.forward/1 is a pass-through (1 caller, 1 callee → …)
  promote any of these with --enforce <rule>.

Parameters (effective — defaults unless overridden):
  max_height: 5   enforce: (none)   layers: on   …

What else it does

• Layer assignment & coverage — @ala_layer tags, uses: content matches, module-name and paths: globs, most-specific-wins; reports coverage (the migration worklist) and validity errors.
• mix ala.encode — writes a parallel .ala.md tree encoding every function in the ALA Code Checklist notation (f / [tag] / edges / $ / q), a draft a human completes.
• mix ala.lint.encoding — lints a completed encoding tree for what the notation carries.
• As a library — AlaLint.analyze(path_or_paths, opts) returns a report map; AlaLint.Report.to_text/1 renders it. Point it at any directory without adding a dep.

Using it with a coding agent

examples/AGENTS.example.md is a ready-to-use instructions file that teaches a coding agent (Claude Code, Codex, and the like) to write and review code against the ALA Checklist by hand, whether or not this linter is installed. Copy it to your project root as AGENTS.md or CLAUDE.md. It states the down-only rule, the four-rule core, each checklist item as a do/avoid/ask directive, the standard techniques to reach for, and a self-review the agent runs when the linter is absent. When the linter is present, the agent can also run mix ala.lint --strict for the mechanical half.

Status

Reference implementation for the ALA Checklist. R1/R4/R5 are exact; R2/R3/R6/R7 are labelled heuristics tuned to be low-noise (single-clause dead-private detection, whitespace-free contract strings, generated-file skipping). R7, abstraction height, pass-through, the reference-level R1 signal, and filesystem cohesion are advisory (reported, not scored) unless enforced. Contributions and rule-precision improvements welcome.

License

Licensed under the MIT License. Fork and use freely, including commercially; keep the copyright notice.