ala_lint for Ruby: the checklist on a Rails codebase, straight from the syntax tree

October 5, 2026 · ALA · ala_lint · tooling · Ruby · Rails

The Elixir linter scores a codebase against the ALA Checklist and can encode source into the checklist notation for a reader to finish. For Ruby I wanted the same command line and the same tiers, built against the Ruby edition of the checklist, but without the encoding. Ruby ships its parser as a library now (Prism), and ERB will hand you the Ruby a template compiles to, so the linter reads the syntax tree directly and keeps nothing in between. It needs no gems beyond Ruby’s own.

bin/ala_lint --root path/to/app            # app/, lib/ and config/routes.rb
bin/ala_lint --root app --strict            # score the obtainable advisories too
bin/ala_lint --root app --super-strict      # and the aspirational ones (R11, public_surface)
bin/ala_lint --root app --min-score 80      # the CI gate
bin/ala_lint --root app --require-layers    # fail if any unit matches no layer
bin/ala_lint --root app --enforce r7 --disable r3 --set height.max=4
bin/ala_lint --list-checks

Durable settings live in .ala_lint.rb, a Ruby file that evaluates to a hash. The one thing the linter can’t do without, for the altitude checks, is the layer map, and it is declared, never inferred, for the reason the checklist gives: infer layers from the call graph and every edge drops by construction.

{
  layers: [
    { name: :application, paths: [%r{\Aapp/ala/screens/}, %r{\Aapp/controllers/}, %r{\Aapp/views/(?!components/)}] },
    { name: :domain,      paths: [%r{\Aapp/ala/domain_abstractions/}, %r{\Aapp/views/components/}] },
    { name: :paradigms,   paths: [%r{\Aapp/ala/programming_paradigms/}] },
    { name: :foundation,  paths: [%r{\Aapp/ala/foundation/}, %r{\Aapp/models/}], uses: [/\AApplicationRecord\z/], peer_ok: true }
  ],
  identity_models: %w[Cart],
  checks: { r7: :scored, height: { max: 4 } }
}

A unit is assigned most-specific-wins: its own # @ala_layer name comment, then a uses: match on its superclass or mixins (a record is persistence wherever the file sits), then the first layer whose path or namespace pattern matches. Anything left is reported as unassigned, skipped by the layer-aware checks, and a failure under --require-layers.

What a unit is, and what an edge is

The OO checklist makes the class the natural unit and says nested types belong to their enclosing class, so the linter’s unit is a class or module with its own members (a nested class qualifies to it), an ERB template, a Name = Data.define(...) type, or a file of top-level statements. A module that only nests other classes is a namespace.

Constants resolve the way Ruby looks them up, through lexical nesting and then the unit’s mixins, so include DomainAbstractions in a screen makes CartLines.new an edge to DomainAbstractions::CartLines. Templates are units too: render "components/x" is an edge to the partial, a bare call to a method some helper defines is an edge to the helper, and the compiled template’s _erbout << "..." strings are kept apart as markup, with text nodes and label-like attributes feeding R3 and id=/data-controller= values feeding R5.

Then every edge kind the checklist lists is on the graph: a call on a constant, a new, a superclass (your own class; subclassing ApplicationRecord or ActionController::Base is configuring a lower framework and allowed), include/extend/prepend, a constant reference, a render of a partial, a helper call, and a model callback reaching another unit. With a layer map, R1 flags an edge that flows up or across a peer-forbidden layer. Without one, it degrades to unit cycles.

The checks

The tiers are the Ruby edition’s. Required and scored by default: R1 through R6, R9, R10 and layer validity. Advisory, scored under --strict: R7’s dead privates, pass-throughs, tramp parameters, self-subscription, ports missing from a header comment, a UI component doing I/O, the shared aggregate, height and unit size. Aspirational, scored only under --super-strict: R11 and the public-surface cap. Reported at every tier and scored by none: the composition’s share of functions, the average unit size, unassigned units, outputs no composition names, and the share of composition functions holding logic. R8 is not checked.

What the OO forms add over the Elixir linter:

The public-surface count, scored only at --super-strict, counts a class’s public methods, and a class is not an ALA concept. An abstraction has several ports and in Ruby a port is a public method, so the count is the number of inputs on one abstraction: CartLines at 11 is one value with eleven operations, not eleven abstractions, and a one-method class would be a port per class. The default of 12 sits just above the largest single-concept classes and modules measured across the top Ruby and Elixir variants, with the only modules above it being the ones later split. That is one application’s distribution, so the check stays advisory and tunable.

Reading the output

The report is the Elixir linter’s: a header, the rules-met count, a weighted density score, the share of functions carrying no scored finding, and the findings. Trimmed, from V01:

── ALA Checklist (R1–R11), Ruby and Rails edition ────────────────────────
units: 101 (37 templates)   functions: 204   LOC: 1535
layer coverage: 101/101 units (100%)

Checklist rules met: 6 of 10 checked (11 in the checklist; R8 is judgement)
  R1 NOT met (18)  R2 met  R3 NOT met (1)  R4 met  R5 NOT met (2)  R6 met  R7 met  R8 unchecked  R9 met  R10 NOT met (3)  R11 met

Degree of function compliance: 66/100  (grade C)
Count of compliant functions: 192 / 204  (94% → grade A)

Findings (scored, most severe first):
  [r1] app/views/components/_cart_line.html.erb:3  app/views/components/_cart_line renders app/views/components/_product_line: cross-peer edge inside domain; a UI abstraction rendering a peer component; let the page place both
  [r1] app/ala/domain_abstractions/cart_totals.rb:25  DomainAbstractions::CartTotals#summary calls DomainAbstractions::Pricing: cross-peer edge inside domain; the layer above should wire them (§2.2)
  [r10] app/models/cart_item.rb:5  CartItem belongs_to :product: reads another feature's record through Product; if Product is only the shared identity, list it under identity_models (R10, §6.17.2)
  [r5] app/ala/screens/checkout.rb:76  "checkout_status" also appears in app/views/components/_checkout_status: a name two units agree on (R5, §7.8); keep it in the composition and pass it to both ends, or make both ends one abstraction

Each message carries the section of Spray’s site it rests on and the move the checklist suggests, because a finding you can’t act on is noise.

Precision, and what it got wrong on the way

The honest table in the README says what each check can and can’t see. The short version: R1, R2, R4, R9 and layer validity are exact on what the syntax shows; R3, R5, R6, R10 and R11 are heuristics; a call on an injected object is invisible, as the checklist warned it would be for a dynamically typed language; and JavaScript isn’t read, so a contract between a template’s data-action and a Stimulus controller is a human’s to check.

Running it against V01 found as many tool mistakes as design findings at first, and each became a test: markup under .freeze read as Ruby text; a render path counted as a contract; run as a meaningless name; ApplicationRecord subclasses as own-class inheritance; a paradigm module with an inner Port = Data.define as a data type; session[:x] = ... as handled data; a controller’s view fields as R4 state. The suite is forty-four small projects written to a temp directory, one per check and per exemption, and the precision cases are listed at the end of V01’s lint notes so the heuristics stay honest.

Linting the linter itself (no layer map) gives 92: a few advisories and one real R5 finding, a string two of its own modules agree on.

Learning the plain shape (2026-10-12)

V06 has no port macros: a part’s input is a method, its outputs are the Hash it returns, and a screen wires with one case [part, output] in a method named wire, feeding outputs through run. The linter read that as logic (a case in the composition, fields assigned outside a wiring block) and as handled data (run(:lines, @lines.load(@items.lookup))), 44 findings in all, and scored it 86. Two precision rules, both narrow: a case in wire whose arms all match two symbols is a wiring table, and its arms are wiring blocks; a part’s call fed to run, including a pull passed straight in, is a wire. A case anywhere else is still a branch, and the same pull outside run is still handled data; the suite has both. Re-linting V01 to V05 after the change left every score the same. V06’s one real finding, a helper that pulled five patches out of an arm, was right, and the patches went back in. V07 added two more: out and collect are wiring calls, and parts is the paradigm’s message, left out of the public-surface count along with initialize.

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

Light ALA keeps the layers, calibration at the top and named rules, and drops ports, wiring and screens that only compose. The Ruby linter has the same preset as the Elixir one:

bin/ala_lint --root path/to/app --preset light_ala

or preset: :light_ala in .ala_lint.rb. It is a whitelist of the checks light ALA adopts: R1 to R6, layer, R7 and its size, height and pass-through checks, tramp, subscribe, ui_io, clone, clone_inside, public surface, module averages and unassigned units. Everything else is off: R9’s port checks, R10, R10-aggregate, R11, r11_share, app_share, ports and ports_unwired. A whitelist, so a check added later stays off under the preset until someone decides light ALA adopts it. R9 is one check in this edition, so its ENV and Rails.configuration lookups go off with the port checks. Explicit settings still win, in the order preset, then the file’s checks: level, then --enforce, then --disable; --set changes thresholds, not levels. An unknown preset stops the run with exit 2.

Not adopted. A checklist rule whose checks are all off now reports as not adopted instead of met, and is left out of the count. V07 under the preset:

Checklist rules met: 7 of 7 checked (11 in the checklist; R8 is judgement; 3 not adopted, every check off)
  R1 met  R2 met  R3 met  R4 met  R5 met  R6 met  R7 met  R8 unchecked  R9 not adopted  R10 not adopted  R11 not adopted
Degree of function compliance: 100/100  (grade A)

A project’s own settings override the preset: V08 and V09 set an R11 level in their .ala_lint.rb, so R11 stays adopted for them, its findings advisory.

The Elixir linter also has checks for two of light ALA’s own rules: struct literals outside their builders (builder_literals) and LiveView events that write session data with no guard (stale_session_write). The Ruby edition doesn’t have them yet.

Where it fits

Same answer as before: a gross filter, not a verdict. V02 scores 100 at --super-strict with no scored finding, and its design still records five judgement calls the map makes that the tool can’t. The code is in ala_lint_ruby.

← all posts