Linter Rule: Enforce strict locals comment syntax

Rule: erb-strict-locals-comment-syntax

Description

Ensures that strict locals comments use the exact locals: ( ... ) syntax so they are properly recognized by Rails and tooling. Also validates that only keyword arguments are used (no positional, block, or splat arguments).

Rationale

Strict locals comments declare which locals are expected in a template. Misspellings or malformed syntax silently disable the declaration, leading to confusing runtime errors when required locals are missing.

Additionally, Rails only supports keyword arguments in strict locals declarations. Positional, block, and splat arguments will raise an ActionView::Error at render-time.

This rule catches invalid comment forms and argument types early during development.

Examples

✅ Good

Required keyword argument:

<%# locals: (user:) %>

Keyword argument with default value:

<%# locals: (user:, admin: false) %>

Complex default values:

<%# locals: (items: [], config: {}) %>

No locals (empty):

<%# locals: () %>

Double-splat for optional keyword arguments:

<%# locals: (message: "Hello", **attributes) %>

🚫 Bad

Wrong comment syntax

Missing colon after locals:

<%# locals() %>
Use `locals:` with a colon, not `locals()`. Correct format: `<%# locals: (...) %>`. (erb-strict-locals-comment-syntax)

Singular local instead of locals:

<%# local: (user:) %>
Use `locals:` (plural), not `local:`. (erb-strict-locals-comment-syntax)

Missing colon before parentheses:

<%# locals (user:) %>
Use `locals:` with a colon before the parentheses, not `locals (`. (erb-strict-locals-comment-syntax)

Missing parentheses around parameters:

<%# locals: user %>

Empty locals: without parentheses:

<%# locals: %>

Unbalanced parentheses:

<%# locals: (user: %>

Wrong tag type (must use ERB comment tag)

Ruby comment in execution tag:

<% # locals: (user:) %>
Use `<%#` instead of `<% #` for strict locals comments. Only ERB comment syntax is recognized by Rails. (erb-strict-locals-comment-syntax)
Use `<%#` instead of `<% #`. Ruby comments immediately after ERB tags can cause parsing issues. (erb-comment-syntax)

Unsupported argument types

Positional argument (use user: instead):

<%# locals: (user) %>

Block argument:

<%# locals: (&block) %>

Single splat argument:

<%# locals: (*args) %>

Note: Double-splat (**attributes) IS supported for optional keyword arguments.

Invalid Ruby syntax

Trailing comma:

<%# locals: (user:,) %>

Leading comma:

<%# locals: (, user:) %>

Double comma:

<%# locals: (user:,, admin:) %>

Duplicate declarations

Only one locals: comment is allowed per partial:

<%# locals: (user:) %>
<p>Content</p>
<%# locals: (admin:) %>

References

• Action View - Strict Locals